API Reference

# Install the package
npm install mafs

# Or with yarn/pnpm
yarn add mafs
pnpm add mafs

// app/layout.tsx (Next.js App Router)
import "mafs/core.css"

// Or in main.tsx (Vite)
import "mafs/core.css"

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

function MyFirstChart() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Plot.OfX
        y={(x) => Math.sin(x)}
        color={Theme.indigo}
      />
    </Mafs>
  )
}

// Default: auto-fit, 1:1 aspect ratio
<Mafs height={300}>

// Custom range: x from 0 to 100, y from 0 to 1
// Great for data with very different scales
<Mafs
  height={300}
  viewBox={{ x: [0, 100], y: [0, 1] }}
  preserveAspectRatio={false}
>

// Enable zoom (scroll to zoom, drag to pan)
<Mafs zoom={{ min: 0.5, max: 4 }}>

// Remove padding around the content
<Mafs padding={0}>

// Basic grid
<Coordinates.Cartesian />

// With subdivisions (4 minor lines between major lines)
<Coordinates.Cartesian subdivisions={4} />

// Custom axis labels (show pi multiples on x-axis)
<Coordinates.Cartesian
  xAxis={{ lines: Math.PI, labels: labelPi }}
  yAxis={{ lines: 1 }}
/>

// Custom label formatter
<Coordinates.Cartesian
  xAxis={{
    lines: 1,
    labels: (x) => x === 0 ? "O" : `${x}m`
  }}
/>

<Mafs height={300}>
  <Coordinates.Polar
    subdivisions={2}  // angular subdivisions
    lines={2}         // radial line spacing
  />
  {/* Plot a rose curve in polar coords */}
  <Plot.Parametric
    xy={(t) => {
      const r = 2 + Math.cos(3 * t)
      return [r * Math.cos(t), r * Math.sin(t)]
    }}
    t={[0, 2 * Math.PI]}
    color={Theme.indigo}
  />
</Mafs>

// Single function
<Plot.OfX y={(x) => Math.sin(x)} color={Theme.indigo} />

// Multiple functions overlaid
<Plot.OfX y={(x) => Math.sin(x)} color={Theme.indigo} />
<Plot.OfX y={(x) => x * x * 0.1 - 1} color={Theme.pink} />
<Plot.OfX y={(x) => Math.exp(-x * x)} color={Theme.green} opacity={0.6} />

// With interactive parameter
const point = useMovablePoint([1, 1])
<Plot.OfX
  y={(x) => point.point[1] * Math.sin(x * point.point[0])}
  color={Theme.indigo}
/>

// Sideways parabola: x = y²
<Plot.OfY x={(y) => y * y} color={Theme.pink} />

// Inverse sine (vertical curve)
<Plot.OfY x={(y) => Math.asin(y)} color={Theme.indigo} />

// Lissajous figure
<Plot.Parametric
  xy={(t) => [2 * Math.cos(t), Math.sin(2 * t)]}
  t={[0, 2 * Math.PI]}
  color={Theme.indigo}
/>

// Spiral
<Plot.Parametric
  xy={(t) => [t * 0.2 * Math.cos(t * 3), t * 0.2 * Math.sin(t * 3)]}
  t={[0, 10]}
  color={Theme.pink}
/>

// Heart curve
<Plot.Parametric
  xy={(t) => [
    16 * Math.pow(Math.sin(t), 3) * 0.15,
    (13 * Math.cos(t) - 5 * Math.cos(2*t) - 2 * Math.cos(3*t) - Math.cos(4*t)) * 0.15
  ]}
  t={[0, 2 * Math.PI]}
  color={Theme.pink}
/>

// ── COMMON FUNCTIONS ──
y={(x) => Math.sin(x)}           // Sine wave
y={(x) => Math.cos(x)}           // Cosine wave
y={(x) => Math.tan(x)}           // Tangent (has discontinuities)
y={(x) => Math.exp(x)}           // Exponential growth
y={(x) => Math.log(x)}           // Natural log (x > 0 only)
y={(x) => 1 / x}                 // Hyperbola
y={(x) => Math.abs(x)}           // V-shape
y={(x) => x * x}                 // Parabola
y={(x) => x * x * x}             // Cubic
y={(x) => Math.sqrt(Math.max(0, x))}  // Square root

// ── PARAMETRIC CURVES ──
// Circle of radius r
xy={(t) => [r * Math.cos(t), r * Math.sin(t)]}  t={[0, 2*PI]}

// Ellipse (a, b are semi-axes)
xy={(t) => [a * Math.cos(t), b * Math.sin(t)]}  t={[0, 2*PI]}

// Lissajous (a, b are frequency ratios)
xy={(t) => [A * Math.sin(a*t + d), B * Math.sin(b*t)]}  t={[0, 2*PI*lcm(a,b)]}

// Archimedes spiral
xy={(t) => [k*t*Math.cos(t), k*t*Math.sin(t)]}  t={[0, 6*PI]}

// Rose curve (n petals when n is odd, 2n when even)
xy={(t) => { const r = Math.cos(n*t); return [r*Math.cos(t), r*Math.sin(t)] }}

// Static points
<Point x={2} y={3} color={Theme.indigo} />
<Point x={-1} y={0} color={Theme.pink} />

// Draggable point (see useMovablePoint section)
const p = useMovablePoint([1, 1])
{p.element}  // renders the draggable handle

// Basic vector from origin
<Vector tail={[0, 0]} tip={[3, 2]} color={Theme.indigo} />

// Chain of vectors (tip-to-tail addition)
<Vector tail={[0, 0]} tip={a} color={Theme.blue} />
<Vector tail={a} tip={vec.add(a, b)} color={Theme.pink} />

// Perpendicular vector: rotate 90°
<Vector tail={[0, 0]} tip={[-y, x]} color={Theme.green} />

// Segment: finite line between two points
<Line.Segment point1={[-2, -1]} point2={[2, 1]} color={Theme.indigo} />

// ThroughPoints: infinite line extending to viewport edges
<Line.ThroughPoints point1={[0, 0]} point2={[1, 2]} color={Theme.pink} />

// PointSlope: line through a point with given slope
<Line.PointSlope point={[0, 1]} slope={0.5} color={Theme.green} />

// Dashed line style
<Line.ThroughPoints point1={[0, 0]} point2={[1, 1]} style="dashed" />

<Circle
  center={[0, 0]}
  radius={2}
  color={Theme.indigo}
  fillOpacity={0.08}    // light fill
  strokeOpacity={0.8}   // visible outline
/>

<Ellipse center={[0, 0]} radius={[3, 1.5]} color={Theme.indigo} fillOpacity={0.08} />

<Polygon
  points={[[-2, -1], [2, -1], [1, 2], [-1, 2]]}
  color={Theme.indigo}
  fillOpacity={0.1}
/>

<Text x={0} y={1} size={20}>Hello World</Text>
<Text x={0} y={0} size={14} color={Theme.indigo}>Colored text</Text>

// Attach controls anchor direction:
<Text x={2} y={1} attach="w">  {/* anchored to the west (left) side */}
<Text x={2} y={1} attach="ne"> {/* anchored to the northeast */}

import { useMovablePoint } from "mafs"

function Interactive() {
  const point = useMovablePoint([1, 1])

  // point.point    → [number, number]  — current position
  // point.element  → JSX.Element       — the draggable handle (render this!)
  // point.setPoint → (p) => void       — imperatively move the point

  return (
    <Mafs>
      <Coordinates.Cartesian />
      <Circle center={[0, 0]} radius={vec.mag(point.point)} />
      {point.element}  {/* IMPORTANT: always render this */}
    </Mafs>
  )
}

// Constrain to x-axis (horizontal only)
useMovablePoint([1, 0], {
  constrain: ([x, y]) => [x, 0]
})

// Constrain to y-axis (vertical only)
useMovablePoint([0, 1], {
  constrain: ([x, y]) => [0, y]
})

// Constrain to a circle of radius 2
useMovablePoint([2, 0], {
  constrain: ([x, y]) => {
    const angle = Math.atan2(y, x)
    return [2 * Math.cos(angle), 2 * Math.sin(angle)]
  }
})

// Constrain to a curve: point rides f(x)
useMovablePoint([1, Math.sin(1)], {
  constrain: ([x]) => [x, Math.sin(x)]
})

// Constrain to integers (snap to grid)
useMovablePoint([0, 0], {
  constrain: ([x, y]) => [Math.round(x), Math.round(y)]
})

// Constrain to a range
useMovablePoint([0, 0], {
  constrain: ([x, y]) => [
    Math.max(-3, Math.min(3, x)),
    Math.max(-2, Math.min(2, y))
  ]
})

// Translate: move children by [dx, dy]
<Transform translate={[2, 1]}>
  <Circle center={[0, 0]} radius={1} />  {/* appears at (2, 1) */}
</Transform>

// Rotate: rotate children by angle (radians)
<Transform rotate={Math.PI / 4}>  {/* 45 degrees */}
  <Polygon points={[[-1,-1],[1,-1],[1,1],[-1,1]]} />
</Transform>

// Scale: scale children uniformly or per-axis
<Transform scale={2}>
  <Point x={1} y={1} />  {/* appears at (2, 2) */}
</Transform>

// Combine: transformations compose
<Transform translate={[2, 0]}>
  <Transform rotate={Math.PI / 6}>
    <Circle center={[0, 0]} radius={0.5} />
  </Transform>
</Transform>

import { useStopwatch } from "mafs"

function AnimatedWave() {
  const { time, start, stop } = useStopwatch()

  // time: seconds since start() was called
  // start(): begin incrementing time
  // stop(): pause time at current value

  return (
    <Mafs>
      <Coordinates.Cartesian />
      <Plot.OfX y={(x) => Math.sin(x + time)} color={Theme.indigo} />
      <Point x={0} y={Math.sin(time)} color={Theme.pink} />
    </Mafs>
  )
}

// ── TRAVELING WAVE ──
y={(x) => Math.sin(x - time * 2)}  // moves right
y={(x) => Math.sin(x + time * 2)}  // moves left

// ── ORBITING POINT ──
const x = radius * Math.cos(time * speed)
const y = radius * Math.sin(time * speed)
<Point x={x} y={y} />

// ── DAMPED OSCILLATION ──
const y = amplitude * Math.exp(-decay * time) * Math.cos(omega * time)

// ── GROWING CIRCLE ──
<Circle center={[0,0]} radius={time * 0.5} />

// ── PULSING OPACITY ──
<Circle center={[0,0]} radius={1} fillOpacity={(Math.sin(time * 3) + 1) / 2 * 0.3} />

// ── PARAMETRIC TRAIL (draw curve up to current time) ──
<Plot.Parametric
  xy={(t) => [Math.cos(t), Math.sin(t)]}
  t={[0, time]}  // trail grows over time
/>

import { vec } from "mafs"

// ── BASIC OPERATIONS ──
vec.add([1, 2], [3, 4])           // → [4, 6]
vec.sub([3, 4], [1, 2])           // → [2, 2]
vec.scale([1, 2], 3)              // → [3, 6]
vec.neg([1, -2])                  // → [-1, 2]

// ── MAGNITUDE & DISTANCE ──
vec.mag([3, 4])                   // → 5
vec.dist([0, 0], [3, 4])          // → 5
vec.squareDist([0, 0], [3, 4])    // → 25 (avoids sqrt)

// ── NORMALIZATION ──
vec.normalize([3, 4])             // → [0.6, 0.8]
vec.withMag([3, 4], 10)           // → [6, 8] (same direction, length 10)

// ── ROTATION ──
vec.rotate([1, 0], Math.PI / 2)   // → [0, 1]
vec.rotateAbout([1, 0], Math.PI, [0.5, 0])  // rotate around a center

// ── INTERPOLATION ──
vec.lerp([0, 0], [10, 10], 0.5)   // → [5, 5]
vec.midpoint([0, 0], [4, 4])      // → [2, 2]

// ── DOT PRODUCT ──
vec.dot([1, 0], [0, 1])           // → 0 (perpendicular)
vec.dot([1, 0], [1, 0])           // → 1 (parallel)

import { labelPi } from "mafs"

<Coordinates.Cartesian
  xAxis={{
    lines: Math.PI,       // major lines at every π
    labels: labelPi,      // renders: -2π, -π, 0, π, 2π
  }}
/>

// Combine with subdivisions for finer marks
<Coordinates.Cartesian
  subdivisions={2}       // marks at π/2 intervals
  xAxis={{ lines: Math.PI, labels: labelPi }}
/>

import { Theme } from "mafs"

Theme.indigo   // primary blue-purple (best for main content)
Theme.pink     // secondary accent
Theme.green    // positive / success
Theme.blue     // cool accent
Theme.orange   // warm accent / warnings
Theme.red      // negative / danger
Theme.yellow   // highlight

// Usage on any component:
<Plot.OfX y={Math.sin} color={Theme.indigo} />
<Circle center={[0,0]} radius={1} color={Theme.pink} />
<Vector tail={[0,0]} tip={[2,1]} color={Theme.green} />
<Text x={0} y={0} color={Theme.orange}>Label</Text>

// ❌ BAD: 500 Line.Segments for a trail
{trail.map((pt, i) =>
  i > 0 ? <Line.Segment point1={trail[i-1]} point2={pt} /> : null
)}

// ✅ GOOD: 1 Plot.Parametric for the same trail
<Plot.Parametric
  xy={(t) => {
    const i = Math.floor(t * (trail.length - 1))
    return trail[Math.min(i, trail.length - 1)]
  }}
  t={[0, 1]}
/>

// ❌ BAD: Pre-computing 10000 steps in useMemo on mount
const sim = useMemo(() => {
  for (let i = 0; i < 10000; i++) { ... }  // blocks render
}, [])

// ✅ GOOD: Incremental simulation with useRef
const state = useRef(initialState)
// Compute 2-4 substeps per frame, max
const substeps = Math.min(4, Math.ceil(elapsed / dt))

// In Next.js App Router, mark your component as client-side:
"use client"

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

export function MyChart() {
  return (
    <Mafs height={300}>
      <Coordinates.Cartesian />
      <Plot.OfX y={Math.sin} color={Theme.indigo} />
    </Mafs>
  )
}

// In your server component / page:
import { MyChart } from "./MyChart"

export default function Page() {
  return <MyChart />  // renders on the client
}

import { usePaneContext, useTransformContext } from "mafs"

function CustomOverlay() {
  // Access the current viewport
  const pane = usePaneContext()
  // pane.xMin, pane.xMax, pane.yMin, pane.yMax

  // Access the current transformation matrix
  const transform = useTransformContext()
  // transform.userTransform — the matrix applied by <Transform>
  // transform.viewTransform — the coordinate-to-pixel matrix

  return (
    <g>
      {/* Your custom SVG here */}
      {/* Coordinates are in math-space, not pixels */}
    </g>
  )
}