Headless Architecture

What Makes PivotHead Special?

PivotHead is the first truly headless pivot table engine. But what does "headless" really mean, and why does it matter for you?

What is a Headless Pivot Engine?

A headless pivot engine separates the data processing logic from the visual presentation. Think of it like a powerful engine that does all the heavy lifting of pivot calculations, while giving you complete freedom to design the user interface however you want.

Understanding Headless Architecture

Interactive Architecture Explorer

Click on each layer to explore how PivotHead's architecture works:

Headless Architecture Layers

Click on each layer to learn more

Your Data

JSON, CSV, API

↓

Core Engine

@pivothead/core

Web Component Bridge

@pivothead/webcomponent

↑

Presentation Layer

↓

Your Custom Pivot Table

Headless vs Traditional

Traditional Libraries

• Fixed UI components
• Limited customization
• Framework-specific
• Large bundle size (500KB+)
• Coupled logic and UI
• Breaking changes on updates

PivotHead Headless

• Complete design freedom
• 100% customizable
• Any framework
• Lightweight
• Separated concerns
• Stable core API

Data Flow Example

1

Input Dataconst data = [ { product: 'A', region: 'North', sales: 100 }, { product: 'B', region: 'South', sales: 200 } ];

→

2

Core Engineconst engine = new PivotEngine(data, { rows: ['product'], columns: ['region'], values: ['sales'] });

→

3

Your UI<YourCustomTable data={engine.getPivotData()} theme="dark" interactive />

Key Benefits

Design Freedom

Build exactly the UI your users need. No compromises.

Performance

Lightweight core engine. Only load what you need.

Framework Agnostic

Works with React, Vue, Angular, or vanilla JavaScript.

Easy Testing

Test business logic and UI independently.

Small Bundle

Core engine is ~50KB. Control your bundle size.

Future Proof

Switch frameworks without rewriting pivot logic.

---

1. Core Engine (@pivothead/core)

The brain of PivotHead - pure TypeScript logic with zero UI dependencies.

Responsibilities:

• Data parsing and transformation
• Pivot calculations and aggregations
• Filtering, sorting, and grouping
• State management
• Performance optimization

2. Web Component Layer (@pivothead/webcomponent)

The bridge between your UI and the core engine.

Responsibilities:

• Wraps core engine functionality
• Exposes standardized API
• Handles browser compatibility
• Manages lifecycle events

Key Benefits:

• Works in any framework
• Encapsulated functionality
• Easy integration
• No style conflicts

3. Framework Wrappers (Optional)

Pre-built integrations for popular frameworks.

• @pivothead/react - React hooks and components
• @pivothead/vue - Vue composables and components
• @pivothead/angular - Angular directives and services

Why Headless Matters

Complete Design Freedom

// You control EVERYTHING about the UI
<YourCustomTable>
  <YourCustomHeader />
  <YourCustomRows />
  <YourCustomAggregations />
  <YourCustomFilters />
</YourCustomTable>

Testability

// Test the engine logic independently
import { PivotEngine } from '@pivothead/core';

test('calculates correct sum', () => {
  const engine = new PivotEngine(data);
  expect(engine.getAggregation('sum', 'sales')).toBe(1000);
});

// Test your UI separately
test('renders table correctly', () => {
  render(<YourCustomTable data={mockData} />);
  // Your component tests
});

Real-World Example: Custom Dashboard

Here's how you might use PivotHead's headless architecture to build a custom analytics dashboard:

import { PivotEngine } from '@pivothead/core';
import { MyCustomCard } from './components';

function AnalyticsDashboard({ salesData }) {
  // Core engine handles all pivot logic
  const engine = new PivotEngine(salesData, {
    rows: ['region', 'product'],
    columns: ['quarter'],
    values: ['sales', 'profit']
  });

  // You control the presentation
  return (
    <div className="my-custom-dashboard">
      <MyCustomCard
        title="Q1 Performance"
        data={engine.getQuarterData('Q1')}
        style="gradient-red"
      />
      <MyCustomChart
        type="bar"
        data={engine.getRegionalBreakdown()}
      />
      <MyCustomTable
        data={engine.getFullPivot()}
        theme="dark"
      />
    </div>
  );
}

Notice: You're using the same powerful pivot engine, but the UI is 100% yours!

Getting Started with Headless

*Quick Start**

1. Install the core engine:

   npm install @pivothead/core

2. Use it with your preferred framework:

   # React
   npm install @pivothead/react
   
   # Vue
   npm install @pivothead/vue
   
   # Angular
   npm install @pivothead/angular
   
   # Or use vanilla JS with web components
   npm install @pivothead/webcomponent

3. Build your UI:

   import { usePivot } from '@pivothead/react';
   
   function MyPivotTable() {
     const { data, config, update } = usePivot(rawData);
   
     // Render however you want!
     return <YourCustomUI data={data} />;
   }

When to Use Headless

Architecture Benefits Summary

Feature	Traditional Libraries	PivotHead Headless
UI Flexibility	Limited	Complete
Framework Support	Usually 1-2	Any framework
Customization	CSS overrides	Full control
Testing	Coupled	Independent layers
Updates	Breaking UI changes	Core logic stable
Learning Curve	Library-specific	Standard web dev

---

Remember: With PivotHead, you're not locked into a specific UI. The engine does the hard work, and you create the perfect interface for your users. That's the power of headless architecture!