Overview and Core Purpose
Mafs Brett is an open-source JavaScript library purpose-built for rendering mathematical expressions, diagrams, and interactive exercises in web applications. It emphasizes precision, accessibility, and predictable behavior across browsers, making it suitable for instructional platforms, assessment tools, and exploratory math apps. Rather than embedding raw LaTeX, Mafs Brett parses a concise domain-specific representation and converts it into scalable, interactive SVG with tight coordinate control. This guide explains its architecture, typical integration patterns, configuration options, and long-term maintenance considerations.
Key Architectural Components
The library is organized around small, composable primitives that map cleanly to mathematical concepts. A minimal mental model includes coord systems, objects, and behaviors. Coord systems define the viewport, axes, and scaling; objects represent points, lines, functions, and polygons; behaviors add interactivity like dragging or snapping. This layering keeps complex scenes declarative and testable. Because each primitive is a small, isolated unit, teams can build higher-level abstractions without rewriting core rendering logic.
Coordinate Systems and Viewports
Mafs Brett uses a scene graph where a root coord system defines world units and an attached viewport maps those units to pixels. You can set bounds, padding, and tick spacing to keep diagrams consistent across devices. Because scaling is deterministic, annotations and labels remain legible at different zoom levels. This makes it practical to author exercises once and render them reliably in production.
Primitives and Labels
Core primitives include Line, Segment, Ray, Vector, Function, Circle, Polygon, and Point. Each accepts standardized props for color, weight, opacity, and z-index. Labels are attached declaratively and automatically avoid overlapping geometry when possible. The library also provides helper primitives, such as Grid and Tick Marks, to improve readability without cluttering authoring syntax.
Interactive Features and Pedagogical Design
Beyond static diagrams, Mafs Brett supports draggable points, constrained motion along curves, and input areas that accept freeform expressions. Constraints can enforce perpendicularity, tangency, or specific numeric values, enabling automated feedback. These interactions are expressed as simple rules, which keeps behavior transparent and easier to debug. For educational products, this reduces the gap between authoring intent and learner experience.
Input Areas and Validation
Built-in Input components accept function expressions, coordinates, or inequalities and highlight correctness in real time. Rules can require exact forms, simplified constants, or specific variable names. Because validation runs client-side, authors can provide immediate hints while reserving server-side checks for final scoring. This hybrid approach balances responsiveness with security.
Animation and Timelines
Simple timelines allow easing-based transitions of coordinates, colors, and visibility. You can animate a function sliding into place or a point tracing a curve. Timelines are declarative and pause on user interaction by default, supporting common accessibility expectations. Because animation logic lives in the scene description, it stays synchronized with other changes.
Integration Patterns and Tooling
Mafs Brett ships as an ES module with minimal runtime dependencies, making it suitable for modern bundlers and server-side rendering. Typical integration involves importing the library, defining a scene object, and mounting it to a container. TypeScript definitions are included, and common editors provide autocompletion for primitive props. The project includes a small dev server with hot reload, easing iterative authoring.
Project Structure and Conventions
- Scene Graph: Plain JSON-like objects that describe coord systems, primitives, and behaviors.
- Theming: Color palettes and spacing scales are centralized, enabling consistent branding.
- Testing Utilities: Selectors and matchers for snapshot and property-based tests.
- Build Output: Tree-shakable bundles suitable for CDN and npm consumption.
Comparison to Alternatives
| Library / Approach | Primary Strength | Primary Trade-off |
|---|---|---|
| Mafs Brett | Precise math primitives and deterministic coordinate control | Smaller ecosystem than generic SVG libraries |
| KaTeX / MathJax | Broad LaTeX coverage and mature rendering | Limited interactivity and harder to synchronize with app state |
| Custom SVG + D3 | Maximum flexibility and animation control | Higher implementation burden and more edge-case math handling |
| GeoGebra iframe | Instant interactive graphs and CAS features | Less customizable, heavier embedding, and weaker offline support |
Use Cases and Best Practices
Ideal scenarios include adaptive courseware, auto-graded problem sets, and exploratory tools where learners manipulate parameters. Authors should define a consistent coordinate scale, reuse theme tokens, and keep individual scenes focused on a single concept. For complex apps, compose multiple scenes rather than overloading one viewport. Use labels and constraints to guide attention, and test across devices to ensure legibility.
Accessibility and Localization
Text primitives support Unicode math symbols and RTL-friendly ordering. Authors are encouraged to provide alt text for diagrams and ensure color contrast meets standard thresholds. Input areas should accept multiple equivalent forms (e.g., 1/2 and 0.5) to reduce friction. Because layout is deterministic, it is easier to generate accessible descriptions programmatically.
Maintenance and Versioning
The project follows semantic versioning with a public changelog. Breaking changes are rare and typically limited to major releases; minor releases add primitives and behaviors without removing existing ones. Teams pinning to a specific major version can expect stable APIs, while those on the latest major gain access to improvements and bug fixes. Regular updates reduce the cost of migration when larger changes do appear.