MintWaterfall

CI Security Audit License: MIT Version codecov

A comprehensive TypeScript waterfall chart library built on D3.js v7. Features advanced data processing, statistical analysis, interactive visualizations, and enterprise-grade performance with complete type safety.

Live Demo

Features

Core Visualization

Statistical Analysis

Advanced Data Processing

Performance & Architecture

Installation

npm install mintwaterfall

CDN:

<script src="https://d3js.org/d3.v7.min.js"></script>
<script src="https://unpkg.com/mintwaterfall@latest/dist/mintwaterfall.min.js"></script>

ES Modules:

import {
  waterfallChart,
  createDataProcessor,
  createStatisticalSystem,
} from "mintwaterfall";
import * as d3 from "d3";

Quick Start

const data = [
  {
    label: "Q1 Revenue",
    stacks: [{ value: 45000, color: "#3498db", label: "$45K" }],
    category: "revenue",
  },
  {
    label: "Q2 Growth",
    stacks: [{ value: 30000, color: "#2ecc71", label: "$30K" }],
    category: "revenue",
  },
  {
    label: "Expenses",
    stacks: [{ value: -15000, color: "#e74c3c", label: "-$15K" }],
    category: "expenses",
  },
];

const chart = waterfallChart()
  .width(800)
  .height(400)
  .showTotal(true)
  .theme("corporate")
  .enableAccessibility(true);

d3.select("#chart").datum(data).call(chart);

Advanced Features

Statistical Analysis

import { createStatisticalSystem } from "mintwaterfall";

const stats = createStatisticalSystem();

// Comprehensive statistical summary
const summary = stats.calculateSummary([10, 20, 30, 40, 50]);
// Returns: { mean, median, mode, variance, quartiles, percentiles }

// Outlier detection with IQR method
const outliers = stats.detectOutliers(data, labels);
// Returns: { outliers, cleanData, method, threshold, statistics }

// Trend analysis with forecasting
const trend = stats.analyzeTrend([
  { x: 1, y: 10 },
  { x: 2, y: 20 },
]);
// Returns: { slope, intercept, correlation, rSquared, forecast }

// Data quality assessment
const quality = stats.assessDataQuality(rawData);
// Returns: { completeness, validity, accuracy, issues, recommendations }

Interactive Systems

import { createAdvancedInteractionSystem } from "mintwaterfall";

const interactions = createAdvancedInteractionSystem(container, data);

// Enable drag interactions with constraints
interactions.enableDrag({
  enabled: true,
  axis: "vertical",
  constraints: { minValue: -100, maxValue: 100 },
});

// Enhanced hover detection with Voronoi diagrams
interactions.enableEnhancedHover({
  enabled: true,
  extent: [
    [0, 0],
    [800, 400],
  ],
});

// Force simulation for dynamic layouts
interactions.startForceSimulation({
  enabled: true,
  forces: { collision: true, positioning: true },
  strength: { collision: 0.7, positioning: 0.5 },
});

Advanced Data Processing

import { createAdvancedDataProcessor } from "mintwaterfall";

const processor = createAdvancedDataProcessor();

// Multi-dimensional grouping
const grouped = processor.groupBy(salesData, (d) => d.region);

// Data rollup with custom reducers
const aggregated = processor.rollupBy(
  salesData,
  (values) => d3.sum(values, (d) => d.revenue),
  (d) => d.category,
);

// Cross-tabulation for dimensional analysis
const crossTab = processor.crossTabulate(
  categories,
  quarters,
  (cat, quarter) => ({ category: cat, quarter, key: `${cat}-${quarter}` }),
);

// Time-based aggregation
const timeAggregated = processor.aggregateByTime(
  timeSeriesData,
  (d) => new Date(d.date),
  (d) => d.value,
  "month",
);

Configuration API

Chart Configuration

chart
  .width(800) // Chart dimensions
  .height(400)
  .margin({ top: 20, right: 30, bottom: 40, left: 50 })
  .showTotal(true) // Display total bar
  .stacked(false) // Toggle chart mode
  .barPadding(0.1) // Bar spacing
  .duration(750) // Animation duration
  .theme("corporate") // Theme selection
  .enableAccessibility(true); // WCAG compliance

Accessibility Features

import { createAccessibilitySystem } from "mintwaterfall";

const a11y = createAccessibilitySystem();

// Create accessible chart descriptions
const descriptionId = a11y.createChartDescription(container, data, {
  title: "Quarterly Revenue Analysis",
  summary: "Shows revenue trends across four quarters",
});

// Validate color contrast
const contrast = a11y.validateColorContrast("#3498db", "#ffffff");
// Returns: { ratio, passesAA, passesAAA, level }

// Handle keyboard navigation
a11y.handleChartKeydown(keyEvent, data, config);

Event Handling

chart.on("barClick", (event, d) => {
  console.log("Clicked:", d.label, d.value);
});

chart.on("brushEnd", (selection) => {
  console.log("Selected range:", selection);
});

// Advanced interaction events
interactions.on("dragStart", (event) => {
  console.log("Drag started:", event);
});

interactions.on("hoverEnter", (data) => {
  console.log("Hover detected:", data);
});

Data Formats

Basic Waterfall Data

const waterfallData = [
  {
    label: "Category Name",
    stacks: [
      { value: 100, color: "#3498db", label: "Positive" },
      { value: -25, color: "#e74c3c", label: "Negative" },
    ],
    category: "revenue",
  },
];

Advanced Processing Data

const businessData = [
  {
    region: "North",
    product: "Widget",
    revenue: 100000,
    date: "2024-01-15",
    category: "sales",
  },
  {
    region: "South",
    product: "Gadget",
    revenue: 85000,
    date: "2024-01-20",
    category: "sales",
  },
];

Themes

Available themes: default, dark, corporate, accessible, colorful, financial, professional

chart.theme("corporate");

// Custom theme configuration
chart.themeConfig({
  background: "#ffffff",
  colors: ["#3498db", "#2ecc71", "#e74c3c"],
  text: "#2c3e50",
  grid: "#ecf0f1",
});

Development

Setup

git clone https://github.com/coredds/MintWaterfall.git
cd MintWaterfall
npm install

Commands

npm test              # Run full test suite (338 tests)
npm run test:core     # Run core functionality tests (136 tests)
npm run test:fast     # Run tests with parallel execution
npm run lint          # ESLint code quality checks
npm run build         # Production build (4 bundle formats)
npm start             # Development server (localhost:8080)

Build Output

Test Coverage

Performance Metrics

Browser Compatibility

Requirements: ES6 Modules, D3.js v7+, SVG support
Tested: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+

Architecture

Module Structure

Recent Updates

v0.8.8 (Current)

v0.8.7

Contributing

Contributions welcome. Requirements:

See CONTRIBUTING.md for detailed guidelines.

License

MIT License - see LICENSE file for details.