MintWaterfall

MintWaterfall v0.8.7

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.7 (Current)

Contributing

Contributions welcome. Requirements:

See CONTRIBUTING.md for detailed guidelines.

License

MIT License - see LICENSE file for details.