Fractionability

A lightweight, accessible JavaScript library for fraction manipulation and display

Fractionability transforms decimals, strings, mixed numbers, percentages, and ratios into simplified, screen-reader-friendly fractions with ease. Featuring MathML support, arithmetic operations, and a fluid API, it’s the ultimate tool for building inclusive web applications perfect for educational tools, recipe apps, financial calculators, and beyond.

---

Why I made it?

I saw how plain linear fractions like 1/2 or 3 1/2 confuse screen readers, excluding visually impaired users. Fractionability bridges this gap with:

• Effortless Conversion: Turns diverse inputs into consistent fraction objects.
• Accessibility Focus: Delivers MathML with natural aria-labels for screen readers.
• Developer-Friendly API: Supports chaining and standalone functions for versatility.
• Real-World Utility: Streamlines tasks like recipe scaling and bill splitting.

Note: Designed for fraction handling and display, not complex equation solving. Pair with MathML or specialized libraries for advanced math.

---

Features

• Input Parsing: Convert decimals (0.75 → 3/4), strings ('3/4'), mixed numbers ('1 1/2'), percentages ('50%'), and ratios ('2:3') into fractions.
• Auto-Simplification: Instantly reduces fractions (e.g., '4/8' → '1/2').
• Arithmetic: Add, subtract, multiply, and divide with precision.
• Comparisons: Check equality and proper/improper status.
• Output Options: Render as decimals, mixed numbers, strings, or MathML.
• Chainable API: Fluent method chaining (e.g., fraction('2/3').add('1/2')).
• Expression Evaluation: Compute expressions like '3 * 1/6'.
• Accessibility: MathML with clear, screen-reader-ready labels.

Pro Tip: Search f13y on npm for faster installation and autocompletion!

---

Installation

Via npm

npm install fractionability

Via Yarn

yarn add fractionability

Via Alias (Shorthand)

npm install f13y@npm:fractionability

Manual Setup

git clone https://github.com/waiz3ple/fractionability.git
cd fractionability
npm install
npm run build

---

Getting Started

ES Modules (ESM)

import { fraction, evaluate, isProper, isEqual } from 'fractionability';
// Or with alias
import { fraction, evaluate, isProper, isEqual } from 'f13y';

CommonJS (CJS)

const { fraction, evaluate, isProper, isEqual } = require('fractionability');
// Or with alias
const { fraction, evaluate, isProper, isEqual } = require('f13y');

Tip: Works seamlessly with both ESM and CJS—pick your style!

---

Usage Examples

Creating Fractions

const { fraction } = require('fractionability');

console.log(fraction('3/4').toString());      // '3/4'
console.log(fraction(0.5).toString());        // '1/2'
console.log(fraction('-1 1/2').toString());   // '-3/2'
console.log(fraction('50%').toString());      // '1/2'
console.log(fraction('2:3').toString());      // '2/3'

Arithmetic

const { fraction, add } = require('fractionability');

const frac = fraction('2/3');
console.log(frac.add('1/2').toString());      // '7/6'
console.log(add('5/6', '1/3').toString());    // '7/6'

Chaining

const { fraction } = require('fractionability');

const result = fraction('7/3').multiply(2).toMixedNumber();
console.log(result); // '4 2/3'

MathML Output

const { fraction } = require('fractionability');

console.log(fraction('-5/2').toStack());
// '<math aria-label="negative 2 and 1 over 2"><mo>-</mo><mn>2</mn><mfrac><mn>1</mn><mn>2</mn></mfrac></math>'
console.log(fraction('3/4').toMathML());
// '<math aria-label="3 over 4"><mfrac><mn>3</mn><mn>4</mn></mfrac></math>' (for backward compatibility)

---

Real-World Scenarios

Recipe Scaling

Goal: Triple 1/3 cup of flour for a larger batch.

const { fraction, multiply } = require('fractionability');

const flour = fraction('1/3');
console.log(multiply(flour, 3).toString()); // '1'

Bill Splitting

Goal: Divide a $150 bill in a 2:3 ratio.

const { fraction, multiply, subtract } = require('fractionability');

const total = 150;
const share1 = multiply(total, fraction('2/5')); // 2/(2+3)
const share2 = subtract(total, share1);
console.log(share1.toString(), share2.toString()); // '60', '90'

Educational Tool

Goal: Visualize 7/3 for a lesson.

const { fraction } = require('fractionability');

const frac = fraction('7/3');
console.log(frac.toMixedNumber()); // '2 1/3'
console.log(frac.toStack());
// '<math aria-label="2 and 1 over 3"><mn>2</mn><mfrac><mn>1</mn><mn>3</mn></mfrac></math>'

Construction Project

Goal: Sum 1 3/4 and 2 1/2 feet.

const { fraction, add } = require('fractionability');

const total = add('1 3/4', '2 1/2');
console.log(total.toMixedNumber()); // '4 1/4'

Interest Calculation

Goal: Compute 7% interest on $500.

const { fraction, multiply } = require('fractionability');

const interest = multiply(500, fraction('7%'));
console.log(interest.toDecimal()); // 35

---

API Highlights

Standalone Functions

• add(f1, f2): Adds two fractions.
• divide(f1, f2): Divides fractions.
• multiply(f1, f2): Multiplies fractions.
• subtract(f1, f2): Subtracts fractions.
• evaluate(expression): Evaluates fraction expressions (e.g., '1/2 + 1/3').
• fraction(value): Creates a Fraction instance.
• isEqual(f1, f2): Checks fraction equality.
• isProper(fraction): Tests if a fraction is proper.

Chainable Methods

• .add(value): Adds a fraction.
• .divide(value): Divides by a fraction.
• .multiply(value): Multiplies by a fraction.
• .subtract(value): Subtracts a fraction.
• .toString(): Returns a fraction string (e.g., '3/4').
• .toMixedNumber(): Returns a mixed number (e.g., '1 2/3').
• .toDecimal(): Returns a decimal value.
• .toStack(): Returns vertical MathML for accessible display (e.g., <math aria-label="3 over 4"><mfrac><mn>3</mn><mn>4</mn></mfrac></math>).
• .toMathML(): Returns standard MathML (for backward compatibility, same as toStack()).
• .toSkew(): Returns a slanted, diagonal fraction, prioritizing MathML with bevelled="true" if supported, or an accessible HTML/CSS fallback.

---

React Integration

Recipe Scaler

import React from 'react';
import { fraction } from 'fractionability';

const RecipeScaler = ({ amount }) => {
  const scaled = fraction(amount).multiply(3).toMixedNumber();
  return <p>Scaled: {scaled} cups</p>;
};

// <RecipeScaler amount="2/3" /> → "Scaled: 2 cups"

Financial Widget

import React from 'react';
import { fraction, multiply } from 'fractionability';

const InterestWidget = ({ principal, rate }) => {
  const interest = multiply(principal, fraction(rate)).toDecimal();
  return <p>Interest: ${interest.toFixed(2)}</p>;
};

// <InterestWidget principal={1000} rate="5%" /> → "Interest: $50.00"

---

Accessibility Matters

Fractionability ensures inclusivity with:

• MathML Output: Descriptive aria-labels (e.g., "two and one over three" for 7/3).
• Normalized Fractions: Clear, simplified representations for all users.

A simple fraction like 3/4 becomes:
And 7/3 becomes:

---

Contributing

Help us enhance accessibility:

1. Fork the repository: github.com/waiz3ple/fractionability
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -m "Add your feature"
4. Push and submit a pull request.

For Contributors: Build and Test

To contribute effectively, you may need to build and test the library locally. These steps are optional and intended for contributors:

Build the Library

Generate the distributable files (dist/index.js, dist/index.cjs, dist/index.d.ts):

npm run build

Note: Ensure dependencies are installed (npm install) before building.

Run Unit Tests

Verify your changes with our comprehensive test suite:

npm run test

Tip: Use npm run test:watch for continuous testing during development.

Run Manual Test

Test the build manually:

node usage.js

---

License

MIT License

---

Support

Questions or issues? Visit GitHub Issues.

---

Disclaimer

Fractionability excels in fraction manipulation and display. For advanced equations, combine with MathML or other tools.

---

Unlock inclusive fraction handling with Fractionability.