Mafs

https://github.com/stevenpetryk/mafs
Admin
Mafs is a library of React components designed for creating interactive, highly customizable, and...
Tokens:58,680
Snippets:391
Trust Score:9.6
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies and start development server

Source: https://github.com/stevenpetryk/mafs/blob/main/README.md

Run these commands in the project root to install dependencies and start the Next.js development server. The server imports Mafs components from src/ and is available at localhost:3000.

```bash
pnpm install
pnpm start
```

--------------------------------

### useMovable usage example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/hooks.md

Example component using useMovable with a ref to an SVGGElement and a MovablePointDisplay to render a draggable point.

```tsx
import { useRef, useState } from "react"
import { Mafs, MovablePointDisplay, useMovable, vec } from "mafs"

export default function App() {
  const ref = useRef<SVGGElement>(null)
  const [point, setPoint] = useState<vec.Vector2>([0, 0])
  const { dragging } = useMovable({
    gestureTarget: ref,
    onMove: setPoint,
    point,
    constrain: (p) => p, // no constraint
  })

  return (
    <Mafs height={300}>
      <MovablePointDisplay ref={ref} point={point} dragging={dragging} />
    </Mafs>
  )
}
```

--------------------------------

### VectorField with Per-Point Opacity

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/plot.md

An example demonstrating how to use the xyOpacity prop to control the visibility of vectors based on their coordinates.

```tsx
import { Mafs, Coordinates, Plot } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Plot.VectorField
        xy={([x, y]) => [y, x]}
        xyOpacity={([, y]) => Math.max(0, Math.min(1, (y + 3) / 6))}
        step={0.5}
      />
    </Mafs>
  )
}
```

--------------------------------

### usePaneContext example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/hooks.md

Example of using usePaneContext to display the visible x-range. It reads xPaneRange and yPaneRange from the hook and renders the x-range as text. Works inside a <Mafs> component; outside it returns the empty default.

```tsx
import { Mafs, usePaneContext } from "mafs"

function VisibleRange() {
  const { xPaneRange, yPaneRange } = usePaneContext()
  return <span>{`x: [${xPaneRange.join(", ")}]`}</span>
}

export default function App() {
  return (
    <Mafs height={300}>
      <VisibleRange />
    </Mafs>
  )
}
```

--------------------------------

### Plot.OfX usage example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/plot.md

Example showing how to use Plot.OfX to render functions within a Mafs coordinate system.

```tsx
import { Mafs, Coordinates, Plot, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Plot.OfX y={(x) => Math.sin(x)} color={Theme.blue} />
      <Plot.OfX y={(x) => x ** 2} domain={[-2, 2]} style="dashed" />
    </Mafs>
  )
}
```

--------------------------------

### MovablePoint

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/movable-point.md

Documentation for the MovablePoint component, including its props, behavior, and usage examples.

```APIDOC
## MovablePoint

### Description
Interactive draggable point component. It is a controlled component that renders a draggable point and calls `onMove` when the user moves it. It supports mouse/touch drag and keyboard arrow keys, and can be constrained via the `constrain` prop.

### Props

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `point` | `vec.Vector2` | yes | — | The current position `[x, y]` (controlled component — parent owns the state). |
| `onMove` | `(point: vec.Vector2) => void` | yes | — | Called with the new `[x, y]` whenever the user moves the point. |
| `constrain` | `ConstraintFunction` | no | `(point) => point` | Maps the user's attempted position to the "snapped" position (e.g. a line, grid, or circle constraint). |
| `color` | `string` | no | `Theme.pink` | Movable point color (drives `--movable-point-color`). |

### Return

`JSX.Element` — a `<MovablePointDisplay>` wired with `useMovable`. `dragging` state is managed internally.

### Behavior

- **Mouse / touch drag**: `useDrag` from `@use-gesture/react`; movement deltas are transformed from pixels to math space via the inverse view transform; `pickup` point is captured on `first`. Events call `event.stopPropagation()`.
- **Keyboard**: arrow keys move the point in increments of `span/50` (default), `span/200` (with `alt`/`meta`), or `span/10` (with `shift`). The movement is applied via the constraint function and `onMove` is called once the constrained point is at least `span/100` away.
- Uses `useMovable`, which requires an invertible view transform (see [errors](../errors.md)).

### Examples

Basic controlled usage:

```tsx
import { useState } from "react"
import { Mafs, Coordinates, MovablePoint, Theme, vec } from "mafs"

export default function App() {
  const [a, setA] = useState<vec.Vector2>([1, 1])

  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <MovablePoint point={a} onMove={setA} color={Theme.blue} />
    </Mafs>
  )
}
```

Constrained to a circle of radius 2:

```tsx
import { useState } from "react"
import { Mafs, Coordinates, MovablePoint, vec } from "mafs"

export default function App() {
  const [a, setA] = useState<vec.Vector2>([2, 0])

  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <MovablePoint
        point={a}
        onMove={setA}
        constrain={(position) => vec.scale(vec.normalize(position), 2)}
      />
    </Mafs>
  )
}
```
```

--------------------------------

### Plot.Parametric Legacy API and Sampling Depth Example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/plot.md

Demonstrates the legacy t-based API and how to tune sampling depth for high-frequency functions.

```tsx
import { Mafs, Coordinates, Plot } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      {/* Legacy: `t` instead of `domain`. Increasing minSamplingDepth improves
          fidelity of high-frequency functions at a performance cost. */}
      <Plot.Parametric
        xy={(t) => [t, Math.sin(1 / t)]}
        t={[-1, 1]}
        minSamplingDepth={12}
        maxSamplingDepth={16}
      />
    </Mafs>
  )
}
```

--------------------------------

### useStopwatch animation example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/hooks.md

React component using useStopwatch to animate a point from x = -3 to x = 2 over 5 seconds. The start and stop buttons control the timer, and the point's x coordinate is derived from the elapsed time.

```tsx
import { Mafs, Coordinates, Point, useStopwatch } from "mafs"

export default function App() {
  const { time, start, stop } = useStopwatch({ startTime: 0, endTime: 5 })

  return (
    <div>
      <button onClick={start}>start</button>
      <button onClick={stop}>stop</button>
      <Mafs height={300}>
        <Coordinates.Cartesian />
        {/* A point that slides from x = -3 to x = 2 over 5 seconds */}
        <Point x={2 - time} y={0} />
      </Mafs>
    </div>
  )
}
```

--------------------------------

### Custom Interactive Point Example with MovablePointDisplay

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/movable-point.md

Example usage of MovablePointDisplay with useMovable to create a draggable point. The component is wrapped in a Mafs view, and the ref is passed to the display for gesture handling.

```tsx
import { useRef, useState } from "react"
import { Mafs, MovablePointDisplay, useMovable, Theme, vec } from "mafs"

export default function App() {
  const ref = useRef<SVGGElement>(null)
  const [point, setPoint] = useState<vec.Vector2>([0, 0])
  const { dragging } = useMovable({ gestureTarget: ref, onMove: setPoint, point, constrain: (p) => p })

  return (
    <Mafs height={300}>
      <MovablePointDisplay ref={ref} point={point} dragging={dragging} color={Theme.green} />
    </Mafs>
  )
}
```

--------------------------------

### useTransformContext example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/hooks.md

Example of using useTransformContext to convert a math-space point to screen coordinates. It multiplies the view and user transforms and applies the result to the point, then renders the coordinates as SVG text. Requires rendering inside a <Mafs> component.

```tsx
import { Mafs, useTransformContext, vec } from "mafs"

function ScreenPosition({ x, y }: { x: number; y: number }) {
  const { viewTransform, userTransform } = useTransformContext()
  const [px, py] = vec.transform([x, y], vec.matrixMult(viewTransform, userTransform))
  return <text x={px} y={py}>{`(${x}, ${y})`}</text>
}

export default function App() {
  return (
    <Mafs height={300}>
      <ScreenPosition x={1} y={1} />
    </Mafs>
  )
}
```

--------------------------------

### MovablePointDisplay

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/movable-point.md

Documentation for the MovablePointDisplay React component, including its props, return type, and a usage example.

```APIDOC
## MovablePointDisplay

### Description
A React component that renders the visual part of a movable point: a hitbox circle, focus ring, ring, and center dot, with hover/focus/drag styling. It forwards its ref to the underlying `<g>` element.

### Signature
```tsx
export interface MovablePointDisplayProps {
  color?: string
  ringRadiusPx?: number
  dragging: boolean
  point: vec.Vector2
}

export const MovablePointDisplay = React.forwardRef<SVGGElement, MovablePointDisplayProps>(
  (props: MovablePointDisplayProps, ref) => {
    const { color = Theme.pink, ringRadiusPx = 15, dragging, point } = props
    // ...
  },
)
```

### Props
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `point` | `vec.Vector2` | yes | — | Position to render at. |
| `dragging` | `boolean` | yes | — | Adds the `mafs-movable-point-dragging` class. |
| `color` | `string` | no | `Theme.pink` | Sets `--movable-point-color`. |
| `ringRadiusPx` | `number` | no | `15` | Ring size in px (sets `--movable-point-ring-size`). |

### Return
`React.ForwardRefExoticComponent<MovablePointDisplayProps & React.RefAttributes<SVGGElement>>`. The `<g>` has `tabIndex={0}` so the point is keyboard-focusable.

### Example — custom interactive point
```tsx
import { useRef, useState } from "react"
import { Mafs, MovablePointDisplay, useMovable, Theme, vec } from "mafs"

export default function App() {
  const ref = useRef<SVGGElement>(null)
  const [point, setPoint] = useState<vec.Vector2>([0, 0])
  const { dragging } = useMovable({ gestureTarget: ref, onMove: setPoint, point, constrain: (p) => p })

  return (
    <Mafs height={300}>
      <MovablePointDisplay ref={ref} point={point} dragging={dragging} color={Theme.green} />
    </Mafs>
  )
}
```
```

--------------------------------

### Image

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/image-text-latex.md

Documentation for the Image component from the Mafs library, including its props and usage example.

```APIDOC
## Image

### Description
Renders an SVG `<image>` positioned in math coordinates. Flipped vertically so the image isn't upside down in Mafs' y-up coordinate system (via a `scaleY(-1)` CSS transform).

### Signature
```tsx
export interface ImageProps {
  href: string
  x: number
  y: number
  anchor?: Anchor
  width: number
  height: number
  preserveAspectRatio?: string
  svgImageProps?: React.SVGProps<SVGImageElement>
}

export function Image({
  href,
  x,
  y,
  width,
  height,
  anchor = "bl",
  preserveAspectRatio,
  svgImageProps,
}: ImageProps)
```

### Parameters
- **href** (string) - Required - Image URL / data URI.
- **x** (number) - Required - Anchor x position in math coordinates.
- **y** (number) - Required - Anchor y position in math coordinates.
- **width** (number) - Required - Width in math units.
- **height** (number) - Required - Height in math units.
- **anchor** (Anchor) - Optional - Default: `"bl"` - Which corner/edge of the image the `x`/`y` refers to (`tl`, `tc`, `tr`, `cl`, `cc`, `cr`, `bl`, `bc`, `br`).
- **preserveAspectRatio** (string) - Optional - Default: `undefined` - SVG `preserveAspectRatio` attribute (e.g. `"none"` to squish). Default keeps the image aspect ratio (SVG default `xMidYMid meet` equivalent).
- **svgImageProps** (React.SVGProps<SVGImageElement>) - Optional - Spread onto the `<image>`.

### Example
```tsx
import { Mafs, Image } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Image href="https://example.com/logo.svg" x={0} y={0} width={2} height={2} anchor="cc" />
    </Mafs>
  )
}
```
```

--------------------------------

### Polyline usage example (TSX)

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/shapes.md

Renders an open polyline through given points using the Polyline component inside a Mafs scene. Demonstrates setting points and weight.

```tsx
import { Mafs, Coordinates, Polyline } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Polyline
        points={[
          [-2, 1],
          [-0.5, -1],
          [1, 0.5],
          [2, -1],
        ]}
        weight={3}
      />
    </Mafs>
  )
}
```

--------------------------------

### Example: Using Circle inside Mafs

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/shapes.md

Renders a filled and a dashed circle. The dashed circle uses fillOpacity={0} and strokeStyle="dashed".

```tsx
import { Mafs, Circle, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Circle center={[0, 1]} radius={2} color={Theme.blue} />
      <Circle center={[2, -1]} radius={0.75} fillOpacity={0} strokeStyle="dashed" />
    </Mafs>
  )
}
```

--------------------------------

### Import and use vec.add and vec.matrixBuilder

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/vec.md

Shows basic usage of the vec namespace: adding two vectors and building a matrix with the matrixBuilder. The matrix builder chains translate and scale, then returns the matrix via get().

```ts
import { vec } from "mafs"

// vector
vec.add([1, 2], [3, 4]) // [4, 6]

// matrix builder
const m = vec.matrixBuilder().translate(10, 10).scale(2).get()
```

--------------------------------

### Basic Transform usage with translate and rotate

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/transform.md

Basic usage example that translates and rotates a circle. The transform is applied to the circle in math space.

```tsx
import { Mafs, Coordinates, Transform, Circle, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Transform translate={[1, 0]} rotate={Math.PI / 4}>
        <Circle center={[0, 0]} radius={1} color={Theme.blue} />
      </Transform>
    </Mafs>
  )
}
```

--------------------------------

### Usage example for Line.PointSlope

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/line.md

Renders a Mafs scene with a Line.PointSlope passing through [0,0] with slope 2, colored with Theme.orange.

```tsx
import { Mafs, Line, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Line.PointSlope point={[0, 0]} slope={2} color={Theme.orange} />
    </Mafs>
  )
}
```

--------------------------------

### Transform (component)

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/transform.md

Documentation for the Transform component from the Mafs library, including its props, return value, composition order, and usage examples.

```APIDOC
## Transform (component)

### Description
A wrapper that applies a linear transformation (and optional translation) to the math-coordinate system of its children by pushing a new `userTransform` into `TransformContext`. Nested `<Transform>` components compose — the innermost transform applies first in math space.

### Signature
```tsx
export type TransformProps = React.PropsWithChildren<{
  matrix?: vec.Matrix
  translate?: vec.Vector2
  scale?: number | vec.Vector2
  rotate?: number
  shear?: vec.Vector2
}>

export function Transform(props: TransformProps)
```

### Props
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | Content to transform. |
| `matrix` | `vec.Matrix` | no | — | If provided, applied first (as the base of the transform builder). |
| `translate` | `vec.Vector2` | no | — | Translation `[tx, ty]`. |
| `scale` | `number \| vec.Vector2` | no | — | Uniform scale (number) or per-axis scale `[sx, sy]`. |
| `rotate` | `number` | no | — | Rotation in radians (counterclockwise, since y points up). |
| `shear` | `vec.Vector2` | no | — | Shear `[x, y]` (matrix `[[1, y], [x, 1]]` in builder convention). |

All transform props except `matrix` are applied **in prop order** (the component iterates `Object.entries(transforms)` in declaration order, skipping `null`/`undefined` values). `matrix` is always applied first regardless of position in the props list.

### Return
`JSX.Element` — a `<TransformContext.Provider>` wrapping a `<g>` whose `--mafs-user-transform` CSS custom property is set to the computed matrix (`vec.toCSS`). Children that read `useTransformContext()` see the new `userTransform`; components that use CSS transforms (e.g. `Plot.OfX` paths) pick up the change automatically.

### Composition & order
The source composes via:

```ts
let builder = vec.matrixBuilder()
if (matrix) builder = builder.mult(matrix)
for (const [name, value] of Object.entries(transforms)) { /* translate, scale, shear, rotate in prop order */ }
builder = builder.mult(userTransform)
```

In `vec.matrixBuilder`, later calls post-multiply, so listed operations apply in the order they appear — e.g. `translate` then `rotate` rotates around the translated origin. Nested `<Transform>` components multiply against the parent's `userTransform`.

### Examples
Basic usage — translate and rotate a shape:

```tsx
import { Mafs, Coordinates, Transform, Circle, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Transform translate={[1, 0]} rotate={Math.PI / 4}>
        <Circle center={[0, 0]} radius={1} color={Theme.blue} />
      </Transform>
    </Mafs>
  )
}
```

Per-axis scaling of a composite, and a plain matrix:

```tsx
import { Mafs, Transform, Polygon, vec } from "mafs"

export default function App() {
  const points: vec.Vector2[] = [
    [0, 0],
    [1, 0],
    [1, 1],
    [0, 1],
  ]

  return (
    <Mafs height={300}>
      <Transform scale={[2, 0.5]}>
        <Polygon points={points} />
      </Transform>
      <Transform matrix={vec.matrixBuilder().rotate(Math.PI / 2).get()} translate={[2, 0]}>
        <Polygon points={points} />
      </Transform>
    </Mafs>
  )
}
```
```

--------------------------------

### Plot.Inequality region between two functions

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/plot.md

Example showing how to shade the region between two sine-based functions of x.

```tsx
import { Mafs, Coordinates, Plot, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Plot.Inequality
        y={{
          "<=": (x) => Math.sin(x) + 1,
          ">": (x) => Math.sin(x) - 1,
        }}
        color={Theme.green}
      />
    </Mafs>
  )
}
```

--------------------------------

### Plot.Inequality one-sided inequality against constants

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/plot.md

Example demonstrating one-sided inequalities against constant values for both x and y.

```tsx
import { Mafs, Coordinates, Plot } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      {/* Region above y = 0 */}
      <Plot.Inequality y={{ ">": 0 }} />
      {/* Region left of x = 1 */}
      <Plot.Inequality x={{ "<": 1 }} />
    </Mafs>
  )
}
```

--------------------------------

### StopwatchArguments

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/types.md

Arguments for the useStopwatch hook. Defines optional start and end times for the stopwatch.

```APIDOC
## StopwatchArguments

### Description
Arguments for the useStopwatch hook. Defines optional start and end times for the stopwatch.

### Fields
- **startTime** (`number`) - Optional - Initial time in seconds (default `0`).
- **endTime** (`number`) - Optional - Stop time in seconds (default `Infinity`).

### TypeScript Definition
```ts
export interface StopwatchArguments {
  startTime?: number
  endTime?: number
}
```
```

--------------------------------

### Point usage example with Mafs and Coordinates

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/shapes.md

Renders two Point components inside a Mafs with Cartesian coordinates. The first point is at (-1, 2) with Theme.red color, the second at (2, -1) with Theme.blue and 0.5 opacity.

```tsx
import { Mafs, Coordinates, Point, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Point x={-1} y={2} color={Theme.red} />
      <Point x={2} y={-1} color={Theme.blue} opacity={0.5} />
    </Mafs>
  )
}
```

--------------------------------

### Per-axis scaling and matrix transform

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/transform.md

Example showing per-axis scaling and a plain matrix transform. The first Transform scales the polygon, the second applies a rotation matrix and a translation.

```tsx
import { Mafs, Transform, Polygon, vec } from "mafs"

export default function App() {
  const points: vec.Vector2[] = [
    [0, 0],
    [1, 0],
    [1, 1],
    [0, 1],
  ]

  return (
    <Mafs height={300}>
      <Transform scale={[2, 0.5]}>
        <Polygon points={points} />
      </Transform>
      <Transform matrix={vec.matrixBuilder().rotate(Math.PI / 2).get()} translate={[2, 0]}>
        <Polygon points={points} />
      </Transform>
    </Mafs>
  )
}
```

--------------------------------

### Polygon usage example (TSX)

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/shapes.md

Renders a filled triangle using the Polygon component inside a Mafs scene with Cartesian coordinates. Demonstrates setting points and color.

```tsx
import { Mafs, Coordinates, Polygon, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Polygon
        points={[
          [-1, -1],
          [1, -1],
          [0, 1],
        ]}
        color={Theme.green}
      />
    </Mafs>
  )
}
```

--------------------------------

### Using theme colors on shapes and a plot

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/theme.md

Example using theme colors on shapes and a plot. Demonstrates applying Theme.red, Theme.blue, and Theme.yellow to Plot.OfX, Circle, and Point components.

```tsx
import { Mafs, Coordinates, Plot, Circle, Point, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Plot.OfX y={Math.sin} color={Theme.red} />
      <Circle center={[0, 0]} radius={1.5} color={Theme.blue} />
      <Point x={0} y={0} color={Theme.yellow} />
    </Mafs>
  )
}
```

--------------------------------

### Basic polar grid example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/coordinates.md

Renders a basic polar grid with concentric rings spaced 0.5 math units apart. Uses the Mafs component with a viewBox from -5 to 5 on both axes.

```tsx
import { Mafs, Coordinates } from "mafs"

export default function App() {
  return (
    <Mafs height={300} viewBox={{ x: [-5, 5], y: [-5, 5] }}>
      <Coordinates.Polar lines={0.5} />
    </Mafs>
  )
}
```

--------------------------------

### Consumer setup: import Mafs CSS and component

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/configuration.md

Required import for correct rendering: import 'mafs/core.css'. Optional import for the serif font: 'mafs/font.css'. The Mafs component is imported from 'mafs'. React 18+ is required as a peer dependency.

```tsx
import "mafs/core.css"          // required for correct rendering
import { Mafs } from "mafs"     // optional: "mafs/font.css" for the serif font
```

--------------------------------

### Basic usage with grid and plot

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/mafs.md

A basic example rendering a Mafs view with a Cartesian coordinate grid and a plot of y = x^2. It sets a fixed height of 300 pixels and uses the default viewBox.

```tsx
import { Mafs, Coordinates, Plot, Theme } from "mafs"
import "mafs/core.css"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Plot.OfX y={(x) => x ** 2} color={Theme.blue} />
    </Mafs>
  )
}
```

--------------------------------

### Using Debug.TransformWidget with a Polygon

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/debug.md

Example usage of Debug.TransformWidget wrapping a Polygon. The widget visualizes a 2D transform with movable handles for translation, scale, and rotation.

```tsx
import { Mafs, Coordinates, Debug, Polygon } from "mafs"

export default function App() {
  return (
    <Mafs height={300} viewBox={{ x: [-4, 4], y: [-4, 4] }}>
      <Coordinates.Cartesian />
      <Debug.TransformWidget>
        <Polygon points={[[0, 0], [1, 0], [1, 1], [0, 1]]} />
      </Debug.TransformWidget>
    </Mafs>
  )
}
```

--------------------------------

### Config with fixed viewBox, constrained zoom, and click handling

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/mafs.md

An interactive example configuring a fixed viewBox, a zoom range from 0.5 to 20, panning enabled, and an onClick handler that logs the math coordinates and screen event. It also hides the x-axis of the Cartesian coordinates.

```tsx
import { Mafs, Coordinates, Theme } from "mafs"

export default function Interactive() {
  return (
    <Mafs
      viewBox={{ x: [-10, 10], y: [-10, 10], padding: 1 }}
      zoom={{ min: 0.5, max: 20 }}
      pan
      onClick={(point, event) => {
        console.log("clicked at", point, "screen", event.clientX, event.clientY)
      }}
    >
      <Coordinates.Cartesian xAxis={{ axis: false }} />
    </Mafs>
  )
}
```

--------------------------------

### Plot.Parametric Lissajous Curve Example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/plot.md

An example of plotting a parametric curve using the modern domain-based API.

```tsx
import { Mafs, Coordinates, Plot, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Plot.Parametric
        xy={(t) => [Math.sin(3 * t), Math.cos(5 * t)]}
        domain={[0, 2 * Math.PI]}
        color={Theme.violet}
      />
    </Mafs>
  )
}
```

--------------------------------

### Import all hooks from 'mafs'

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/hooks.md

Import useMovable, useMovablePoint, useStopwatch, useTransformContext, and usePaneContext from the package root.

```tsx
import {
  useMovable,
  useMovablePoint,
  useStopwatch,
  useTransformContext,
  usePaneContext,
} from "mafs"
```

--------------------------------

### Run test suites

Source: https://github.com/stevenpetryk/mafs/blob/main/README.md

Use these pnpm scripts to run the test suites. The first command runs both unit and end-to-end tests, while the others target specific suites. The --update-snapshots flag updates visual test baselines.

```bash
pnpm test      # run both suites
pnpm test:unit # to run just the Jest tests
pnpm test:e2e  # to run Playwright (end-to-end and visual tests)
pnpm test -- --update-snapshots # to update the visual test baselines
```

--------------------------------

### Import all basic shapes from "mafs"

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/shapes.md

Import the built-in geometric display primitives: Circle, Ellipse, Point, Vector, Polygon, and Polyline.

```tsx
import { Circle, Ellipse, Point, Vector, Polygon, Polyline } from "mafs"
```

--------------------------------

### Line.Segment usage example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/line.md

Example of using Line.Segment inside a Mafs component to draw a line segment between two points with custom color and weight.

```tsx
import { Mafs, Line, vec } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Line.Segment point1={[-2, -1]} point2={[2, 1]} color="#f00" weight={3} />
    </Mafs>
  )
}
```

--------------------------------

### Vector usage example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/shapes.md

Example of using the Vector component inside a Mafs scene with Cartesian coordinates, showing two vectors with different colors and weights.

```tsx
import { Mafs, Coordinates, Vector, vec, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Vector tip={[2, 1]} color={Theme.blue} />
      <Vector tail={[-2, -2]} tip={vec.rotate([2, 1], Math.PI / 2)} color={Theme.pink} weight={1} />
    </Mafs>
  )
}
```

--------------------------------

### useMovablePoint(initialPoint, options?)

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/hooks.md

Creates a stateful movable point. Returns an object with the current position, a renderable element, and a setter function.

```APIDOC
## useMovablePoint(initialPoint, options?)

### Description
Stateful movable point: owns the position and returns a ready-to-render `<MovablePoint>` element.

### Signature
```ts
export type ConstraintFunction = (position: vec.Vector2) => vec.Vector2

export interface UseMovablePointArguments {
  color?: string
  constrain?: "horizontal" | "vertical" | ConstraintFunction
}

export interface UseMovablePoint {
  x: number
  y: number
  point: vec.Vector2
  element: React.ReactElement
  setPoint: (point: vec.Vector2) => void
}

export function useMovablePoint(
  initialPoint: vec.Vector2,
  { constrain, color = Theme.pink }: UseMovablePointArguments = {},
): UseMovablePoint
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `initialPoint` | `vec.Vector2` | yes | — | Starting position `[x, y]`. |
| `constrain` | `"horizontal" \| "vertical" \| ConstraintFunction` | no | identity | `"horizontal"` fixes y to `initialPoint[1]`; `"vertical"` fixes x to `initialPoint[0]`; a function maps attempted positions to snapped positions. |
| `color` | `string` | no | `Theme.pink` | Passed to the rendered `MovablePoint`. |

### Returns
`UseMovablePoint`:

| Field | Type | Description |
|-------|------|-------------|
| `x` | `number` | Current x of the point. |
| `y` | `number` | Current y of the point. |
| `point` | `vec.Vector2` | Current position `[x, y]` (fresh array). |
| `element` | `React.ReactElement` | A `<MovablePoint>` bound to this state — render it inside the `Mafs` view. |
| `setPoint` | `(point: vec.Vector2) => void` | Imperatively move the point. |

### Example
```tsx
import { Mafs, Coordinates, useMovablePoint, Theme } from "mafs"

export default function App() {
  const a = useMovablePoint([-2, -1], { color: Theme.blue })
  const b = useMovablePoint([0, 1], { constrain: "horizontal", color: Theme.pink })

  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      {a.element}
      {b.element}
      <Panel a={a} b={b} />
    </Mafs>
  )
}

function Panel({ a, b }: { a: { x: number; y: number }; b: { x: number; y: number } }) {
  return <div>{`a=(${a.x}, ${a.y}) b=(${b.x}, ${b.y})`}</div>
}
```
```

--------------------------------

### Line.PointAngle usage example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/line.md

Example usage of Line.PointAngle inside a Mafs component. It passes a point and an angle in radians (Math.PI / 6). The line is drawn through the point at that angle.

```tsx
import { Mafs, Line } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Line.PointAngle point={[0, 0]} angle={Math.PI / 6} />
    </Mafs>
  )
}
```

--------------------------------

### Import MovablePoint and MovablePointDisplay

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/movable-point.md

Import the MovablePoint and MovablePointDisplay components from the 'mafs' package.

```tsx
import { MovablePoint, MovablePointDisplay } from "mafs"
```

--------------------------------

### matrixBuilder(m?)

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/vec.md

Creates a fluent builder for composing 2D transformations.

```APIDOC
## `matrixBuilder(m?)`

### Description
Returns a builder for composing transformations.

### Signature
`matrixBuilder(m: Matrix | null = null)`

### Parameters
- **m** (Matrix | null) - Optional - An existing matrix to seed the builder.

### Returns
- **builder** - An object with methods:
  - `mult: (m: Matrix) => builder` - Multiply by a matrix.
  - `translate: (x: number, y: number) => builder` - Translate.
  - `rotate: (a: number) => builder` - Rotate by radians.
  - `scale: (x: number, y: number) => builder` - Scale.
  - `shear: (x: number, y: number) => builder` - Shear.
  - `get: () => Matrix` - Returns a copy of the accumulated matrix.

Each method returns a **new** builder.
```

--------------------------------

### Line.ThroughPoints usage example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/line.md

Example usage of Line.ThroughPoints inside a Mafs component. It passes two points and optional styling props (style="dashed", color={Theme.green}). The line extends to the pane edges.

```tsx
import { Mafs, Line, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Line.ThroughPoints point1={[-2, -1]} point2={[2, 1]} style="dashed" color={Theme.green} />
    </Mafs>
  )
}
```

--------------------------------

### LaTeX

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/image-text-latex.md

Renders KaTeX typeset math at a given position. Accepts LaTeX source, a position vector, optional color, and KaTeX options.

```APIDOC
## LaTeX

### Description
Renders KaTeX typeset math at a position. Uses a `foreignObject` (99999×99999) with a `fixed`-position inner div, so it floats above other SVG content; pointer events are disabled (`pointerEvents="none"`).

### Signature
```tsx
interface LatexProps {
  tex: string
  at: vec.Vector2
  color?: string
  katexOptions?: KatexOptions
}

export function LaTeX({ at: center, tex, color = Theme.foreground, katexOptions }: LatexProps)
```

> `LatexProps` is **not** exported from the package entry point; only the component is.

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `tex` | `string` | yes | — | LaTeX source (e.g. `"x^2"`). |
| `at` | `vec.Vector2` | yes | — | Math-coordinate position of the expression. |
| `color` | `string` | no | `Theme.foreground` | Text color. |
| `katexOptions` | `KatexOptions` (from the `katex` package) | no | — | Options passed directly to `katex.render`. |

### Implementation Details
Renders into a `<span>` via `katex.render(tex, ref.current, katexOptions)` in a `useEffect` (re-run when `tex` or `katexOptions` change). Text shadow of `Theme.background` is repeated 8× for legibility.

### Example
```tsx
import { Mafs, Coordinates, LaTeX, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <LaTeX tex="\int_0^1 x^2 \, dx" at={[0, 0.5]} color={Theme.blue} />
    </Mafs>
  )
}
```

With KaTeX options:

```tsx
import { Mafs, LaTeX } from "mafs"

export default function App() {
  return (
    <Mafs height={200}>
      <LaTeX
        tex="f(x) = \\frac{1}{1 + e^{-x}}"
        at={[0, 0]}
        katexOptions={{ displayMode: true, throwOnError: false }}
      />
    </Mafs>
  )
}
```
```

--------------------------------

### useMovablePoint usage example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/hooks.md

Example usage of useMovablePoint in a React component. Creates two movable points, one with a custom color and one constrained horizontally, and renders them inside a Mafs view along with a panel displaying their coordinates.

```tsx
import { Mafs, Coordinates, useMovablePoint, Theme } from "mafs"

export default function App() {
  const a = useMovablePoint([-2, -1], { color: Theme.blue })
  const b = useMovablePoint([0, 1], { constrain: "horizontal", color: Theme.pink })

  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      {a.element}
      {b.element}
      <Panel a={a} b={b} />
    </Mafs>
  )
}

function Panel({ a, b }: { a: { x: number; y: number }; b: { x: number; y: number } }) {
  return <div>{`a=(${a.x}, ${a.y}) b=(${b.x}, ${b.y})`}</div>
}
```

--------------------------------

### Plot.Inequality invalid bounds example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/errors.md

This example triggers the `Plot.Inequality` error "You cannot pass both an inequality and an equality operator to Inequality" by providing both `">"` and `">="` in the same axis object. It is used to demonstrate the invalid bounds error condition.

```tsx
import { Mafs, Plot } from "mafs"

export default function Bad() {
  return (
    <Mafs height={300}>
      {/* Throws: two lower bounds of different strictness */}
      <Plot.Inequality y={{ ">": 0, ">=": 1 }} />
    </Mafs>
  )
}
```

--------------------------------

### Plot.OfY Usage Example

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/plot.md

A basic implementation of Plot.OfY within a Mafs coordinate system.

```tsx
import { Mafs, Coordinates, Plot, Theme } from "mafs"

export default function App() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Plot.OfY x={(y) => Math.sqrt(y)} color={Theme.pink} />
    </Mafs>
  )
}
```

--------------------------------

### useStopwatch(options?)

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/api-reference/hooks.md

A requestAnimationFrame-driven timer for animations, backed by DOMHighResTimeStamp. Returns an object with the current time and methods to control the timer.

```APIDOC
## useStopwatch(options?)

### Description
A requestAnimationFrame-driven timer for animations, backed by DOMHighResTimeStamp. Returns an object with the current time and methods to control the timer.

### Signature
```ts
export interface StopwatchArguments {
  startTime?: number
  endTime?: number
}

export interface Stopwatch {
  time: number
  start: () => void
  stop: () => void
  setTime: (time: number) => void
}

export function useStopwatch(options?: StopwatchArguments): Stopwatch
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `startTime` | `number` | no | `0` | Initial time (seconds). |
| `endTime` | `number` | no | `Infinity` | Time (seconds) at which the stopwatch stops and clamps. |

### Returns

`Stopwatch`:

| Field | Type | Description |
|-------|------|-------------|
| `time` | `number` | Elapsed time in high-precision seconds. |
| `start` | `() => void` | Starts (or resumes) the timer. |
| `stop` | `() => void` | Stops and resets `time` to `startTime`. |
| `setTime` | `(time: number) => void` | Sets the current time. The JSDoc states it "throws an error if the time is outside of the given range", but **the v0.21.0 implementation does not validate** — it stores `time * 1000` directly (see [errors](../errors.md)). |

Note: `time` always reflects `Math.min(deltaTime, endTime)` while playing; `stop()` resets to `startTime`, not `0`.

### Example
```tsx
import { Mafs, Coordinates, Point, useStopwatch } from "mafs"

export default function App() {
  const { time, start, stop } = useStopwatch({ startTime: 0, endTime: 5 })

  return (
    <div>
      <button onClick={start}>start</button>
      <button onClick={stop}>stop</button>
      <Mafs height={300}>
        <Coordinates.Cartesian />
        {/* A point that slides from x = -3 to x = 2 over 5 seconds */}
        <Point x={2 - time} y={0} />
      </Mafs>
    </div>
  )
}
```
```

--------------------------------

### Stopwatch interface

Source: https://github.com/stevenpetryk/mafs/blob/main/_autodocs/types.md

Defines the return type of the useStopwatch hook. Provides time, start, stop, and setTime methods. setTime is unvalidated in v0.21.0.

```TypeScript
export interface Stopwatch {
  time: number
  start: () => void
  stop: () => void
  setTime: (time: number) => void
}
```
Tokens:
Raw