PivotHead

PivotHead is a headlessPivot, powerful and flexible library for creating interactive pivot tables in JavaScript applications. It provides a core engine for data manipulation and, in the future, will be compatible with wrappers for React, Vue, Svelte, and Angular, making it easy to integrate into applications built with these frameworks.

Table of Contents

1. Features
2. Installation
3. Basic Usage
4. PivotEngine API
5. Advanced Features
6. Configuration
7. Examples

Features

• Flexible data pivoting and aggregation
• Sorting capabilities
• Grouping data by multiple fields
• Column resizing
• Drag and drop for rows
• Conditional formatting
• Custom measures and formulas
• Responsive design
• Customizable styling
• React integration (Upcoming)
• Hide and show toolbar
• Export by pdf
• Provide local json file for pivoting

Installation

To install PivotHead, use npm or yarn:

npm install @mindfiredigital/pivothead

Basic Usage

import { PivotEngine } from '@mindfiredigital/pivothead';

const data = [
  {
    date: '2024-01-01',
    product: 'Widget A',
    region: 'North',
    sales: 1000,
    quantity: 50,
  },
  // ... more data
];

const config = {
  data: data,
  rows: [{ uniqueName: 'product', caption: 'Product' }],
  columns: [{ uniqueName: 'region', caption: 'Region' }],
  measures: [
    {
      uniqueName: 'sales',
      caption: 'Total Sales',
      aggregation: 'sum',
      format: {
        type: 'currency',
        currency: 'USD',
        locale: 'en-US',
        decimals: 2,
      },
    },
    {
      uniqueName: 'quantity',
      caption: 'Total Quantity',
      aggregation: 'sum',
      format: {
        type: 'number',
        decimals: 2,
        locale: 'en-US',
      },
    },
  ],
  dimensions: [
    { field: 'product', label: 'Product', type: 'string' },
    { field: 'region', label: 'Region', type: 'string' },
    { field: 'date', label: 'Date', type: 'date' },
    { field: 'sales', label: 'Sales', type: 'number' },
    { field: 'quantity', label: 'Quantity', type: 'number' },
  ],
  defaultAggregation: 'sum',
  isResponsive: true,
  groupConfig: {
    rowFields: ['product'],
    columnFields: ['region'],
    grouper: (item, fields) => fields.map(field => item[field]).join(' - '),
  },
  formatting: {
    sales: {
      type: 'currency',
      currency: 'USD',
      locale: 'en-US',
      decimals: 2,
    },
    quantity: {
      type: 'number',
      decimals: 2,
      locale: 'en-US',
    },
  },
  conditionalFormatting: [
    {
      value: {
        type: 'Number',
        operator: 'Greater than',
        value1: '1000',
        value2: '',
      },
      format: {
        font: 'Arial',
        size: '14px',
        color: '#ffffff',
        backgroundColor: '#4CAF50',
      },
    },
    // ... more conditional formatting rules
  ],
  // Add initial sort configuration
  initialSort: [
    {
      field: 'sales',
      direction: 'desc',
      type: 'measure',
      aggregation: 'sum',
    },
  ],
};

const engine = new PivotEngine(config);

// Use the engine to render your pivot table

PivotEngine API

The PivotEngine class is the core of the PivotHead library. Here are its key methods:

Constructor

constructor(config: PivotTableConfig<T>)

Creates a new instance of PivotEngine with the given configuration.

State Management

getState()

getState(): PivotTableState<T>

Example :-

• getState(): PivotTableState

  Returns the current state of the pivot table.

  const state = engine.getState();
  console.log(state.data); // Logs the current data array
  console.log(state.sortConfig); // Logs the current sort configuration

Returns the current state of the pivot table.

reset()

Resets the pivot table to its initial state.

reset();

Example :-

• reset()

  engine.reset();
  const state = engine.getState();
  console.log(state); // Logs the initial state

Resets the pivot table to its initial state.

Data Manipulation

setMeasures(measureFields: MeasureConfig[])

setMeasures(measureFields: MeasureConfig[])

Sets the measures for the pivot table.

setDimensions(dimensionFields: Dimension[])

setDimensions(dimensionFields: Dimension[])

Sets the dimensions for the pivot table.

setAggregation(type: AggregationType)

setAggregation(type: AggregationType)

Sets the aggregation type for the pivot table.

Formatting

formatValue(value: any, field: string): string

formatValue(value: any, field: string): string

Formats a value based on the specified field's format configuration.

Example:

const formattedValue = engine.formatValue(1000, 'sales');
console.log(formattedValue); // "$1,000.00"

Sorting and Grouping

sort(field: string, direction: 'asc' | 'desc')

sort(field: string, direction: 'asc' | 'desc')

Sorts the pivot table data.

Example:

engine.sort('sales', 'asc');

setGroupConfig(groupConfig: GroupConfig | null)

setGroupConfig(groupConfig: GroupConfig | null)

Sets the group configuration for the pivot table.

getGroupedData(): Group[]

getGroupedData(): Group[]

Returns the grouped data.

Row and Column Manipulation

resizeRow(index: number, height: number)

resizeRow(index: number, height: number)

Resizes a specific row in the pivot table.

toggleRowExpansion(rowId: string)

toggleRowExpansion(rowId: string)

Toggles the expansion state of a row.

isRowExpanded(rowId: string): boolean

isRowExpanded(rowId: string): boolean

Checks if a specific row is expanded.

dragRow(fromIndex: number, toIndex: number)

dragRow(fromIndex: number, toIndex: number)

Handles dragging a row to a new position.

dragColumn(fromIndex: number, toIndex: number)

dragColumn(fromIndex: number, toIndex: number)

Handles dragging a column to a new position.

Advanced Features

Sorting

PivotHead supports sorting for measures and dimensions. You can configure initial sorting and handle sorting dynamically.

Example configuration:

const config = {
  // ... other configuration options
  initialSort: [
    {
      field: 'sales',
      direction: 'desc',
      type: 'measure',
      aggregation: 'sum',
    },
  ],
  // ... other configuration options
};

To handle sorting dynamically, you can use the sort method:

engine.sort('sales', 'asc');

Formatting cells

PivotHead supports conditional formatting for cells like decimal values , currency symbol etc.

Example configuration:

const config = {
  // ... other configuration options
  measures: [
    {
      uniqueName: 'sales',
      caption: 'Total Sales',
      aggregation: 'sum',
      format: {
        type: 'currency',
        currency: 'USD',
        locale: 'en-US',
        decimals: 4,
      },
    },
    {
      uniqueName: 'quantity',
      caption: 'Total Quantity',
      aggregation: 'sum',
      format: {
        type: 'number',
        decimals: 2,
        locale: 'en-US',
      },
    },
    {
      uniqueName: 'averageSale',
      caption: 'Average Sale',
      aggregation: 'avg',
      format: {
        type: 'currency',
        currency: 'USD',
        locale: 'en-US',
        decimals: 4,
      },
      formula: item => item.sales / item.quantity,
    },
  ],
  // ... other configuration options
  formatting: {
    sales: {
      type: 'currency',
      currency: 'USD',
      locale: 'en-US',
      decimals: 4,
    },
    quantity: {
      type: 'number',
      // decimals: 2,
      // locale: 'en-US'
    },
    averageSale: {
      type: 'currency',
      currency: 'USD',
      locale: 'en-US',
      decimals: 4,
    },
  },
};

Conditional Formatting

PivotHead supports conditional formatting, allowing you to apply custom styles to cells based on their values.

Example configuration:

const config = {
  // ... other configuration options
  conditionalFormatting: [
    {
      value: {
        type: 'Number',
        operator: 'Greater than',
        value1: '1000',
        value2: '',
      },
      format: {
        font: 'Arial',
        size: '14px',
        color: '#ffffff',
        backgroundColor: '#4CAF50',
      },
    },
    // ... more conditional formatting rules
  ],
};

Custom Measures

You can define custom measures with specific formulas:

const config = {
  // ... other configuration options
  measures: [
    {
      uniqueName: 'averageSale',
      caption: 'Average Sale',
      aggregation: 'avg',
      format: {
        type: 'currency',
        currency: 'USD',
        locale: 'en-US',
        decimals: 2,
      },
      formula: item => item.sales / item.quantity,
    },
  ],
};

Toolbar visibility

Show hide the hide the visibility of tool using config.

const config = {
  // ... other configuration options

  toolbar: <boolean>
  // ... other configuration options
};

Configuration

The PivotTableConfig object allows you to customize various aspects of the pivot table:

interface PivotTableConfig<T> {
  data: T[];
  rows: { uniqueName: string; caption: string }[];
  columns: { uniqueName: string; caption: string }[];
  measures: MeasureConfig[];
  dimensions: Dimension[];
  defaultAggregation?: AggregationType;
  isResponsive?: boolean;
  groupConfig?: GroupConfig;
  formatting?: Record<string, FormatConfig>;
  conditionalFormatting?: ConditionalFormattingRule[];
}

For detailed information on each configuration option, please refer to the source code and comments.

Examples

To run the examples:

1. Clone the repository
2. Navigate to the examples/vanilla-js-demo folder
3. Install dependencies with npm install or yarn install
4. Build the project with npm run build or yarn build
5. Start the development server with npm start or yarn start
6. Open your browser and navigate to the local host address provided

These examples demonstrate various features of the PivotHead library, including:

• Basic pivot table setup
• Custom measures and formulas
• Grouping and aggregation
• Conditional formatting
• Drag and drop functionality
• Responsive design

For more detailed examples and usage scenarios, please refer to the example files in the repository.

Contributing

We welcome contributions from the community. If you'd like to contribute to the pivothead npm package, please follow our Contributing Guidelines.

License

Copyright (c) Mindfire Digital llp. All rights reserved.

Licensed under the MIT license.