# PeityCharts.js

######

## Elegant Inline Data Visualization

Peity (pronounced "pie-ty") is a simple jQuery plugin that converts element text like "5/10" or "2,5,3,9" into small inline charts. These charts are perfect for showing trends or simple metrics directly alongside text or in tables.

With minimal footprint and easy implementation, Peity charts are ideal for dashboards, reports, and anywhere you need to display data visualizations in a compact format.

Pro Tip: Peity charts work seamlessly with SmartAdmin's color system and can be placed directly inline with text, in tables, or within other UI components for at-a-glance data visualization.

## Installation

Peity is included in the SmartAdmin theme with an ES6 implementation that doesn't require jQuery. Here's how to use it:

#### 1. Including the Script

    // Add the script as a module in your HTML
    <script type="module" src="./thirdparty/peitycharts.js"></script>

    // Or import it in your JavaScript module
    import './thirdparty/peitycharts.js';

#### 2. Automatic Implementation with Data Attributes

    // Once the module is loaded, it will automatically initialize charts with these classes:
    // - .peity-pie
    // - .peity-donut
    // - .peity-line
    // - .peity-bar
    // - Any element with a [data-peity] attribute

    // Simply add elements with the appropriate class:
    <span class="peity-pie">4/7</span>
    <span class="peity-donut">5/8</span>
    <span class="peity-line">5,3,9,6,5,9,7,3,5,2</span>
    <span class="peity-bar">5,3,9,6,5,9,7,3,5,2</span>

    // You can also use the data-peity attribute for custom options:
    <span class="peity-donut" data-peity='{"fill":["var(--success-500)","var(--bs-border-color)"],"innerRadius":20,"radius":40}'>5/8</span>

#### 3. Manual Implementation with Direct API

    // Import the PeityAPI directly in your module
    import { PeityAPI } from './thirdparty/peity.es6.js';

    document.addEventListener('DOMContentLoaded', function() {
        // Create a chart manually
        const element = document.querySelector('.my-custom-chart');
        PeityAPI.create(element, 'pie', {
            fill: ['var(--primary-500)', 'var(--bs-border-color)'],
            radius: 30
        });

        // Create multiple charts with the same options
        document.querySelectorAll('.line-charts').forEach(element => {
            PeityAPI.create(element, 'line', {
                fill: 'var(--info-200)',
                stroke: 'var(--info-500)',
                width: 100,
                height: 30
            });
        });
    });

#### HTML Structure

    <!-- For automatic initialization -->
    <span class="peity-pie">4/7</span>
    <span class="peity-donut">5/8</span>
    <span class="peity-line">5,3,9,6,5,9,7,3,5,2</span>
    <span class="peity-bar">5,3,9,6,5,9,7,3,5,2</span>

    <!-- With data attributes for custom options -->
    <span class="peity-pie" data-peity='{"fill":["var(--primary-500)","var(--bs-border-color)"],"radius":25}'>4/7</span>

    <!-- For manual initialization -->
    <span class="my-custom-chart">4/7</span>

When to use each approach:

- Automatic Implementation: Best for typical use cases. Just add HTML with the proper class and data attributes - minimal JavaScript needed.
- Manual Implementation: Use when you need more control over initialization timing, want to update charts dynamically, or need custom behavior.

Important:

- The SmartAdmin implementation of Peity does not require jQuery - it's a native ES6 module.
- Charts are rendered as SVG elements, which means they scale nicely for retina displays.
- The implementation automatically handles theming with SmartAdmin CSS variables.

## Chart Types

Peity supports four main chart types, each with its own configuration options:

#### Pie Charts

Pie charts display a single value as a portion of a whole. They're ideal for showing percentages or proportions.

    // HTML
    <span class="pie-chart">4/7</span>

    // JavaScript
    \$(".pie-chart").peity("pie", {
        fill: ["var(--primary-500)", "var(--gray-300)"],
        radius: 30,
        innerRadius: 0
    });

#### Donut Charts

Donut charts are similar to pie charts but with a hole in the center. They provide the same information but with a different visual style.

    // HTML
    <span class="donut-chart">5/8</span>

    // JavaScript
    \$(".donut-chart").peity("donut", {
        fill: ["var(--success-500)", "var(--gray-300)"],
        radius: 30,
        innerRadius: 15
    });

#### Line Charts

Line charts display a series of values as a connected line. They're great for showing trends over time.

    // HTML
    <span class="line-chart">5,3,9,6,5,9,7,3,5,2</span>

    // JavaScript
    \$(".line-chart").peity("line", {
        fill: "var(--primary-200)",
        stroke: "var(--primary-500)",
        width: 100,
        height: 30
    });

#### Bar Charts

Bar charts represent values as vertical bars. They're useful for comparing values across categories.

    // HTML
    <span class="bar-chart">5,3,9,6,5,9,7,3,5,2</span>

    // JavaScript
    \$(".bar-chart").peity("bar", {
        fill: ["var(--primary-500)"],
        width: 100,
        height: 30
    });

## Configuration Options

Each chart type has its own set of configuration options:

#### Pie & Donut Options

Option | Type | Default | Description
--- | --- | --- | ---
`fill` | Array | ["#ff9900", "#fff4dd", "#ffc66e"] | The colors of the segments (first value's color, then second, etc.)
`radius` | Number | 8 | The outer radius of the chart in pixels
`innerRadius` | Number | 0 (pie), radius/2 (donut) | The inner radius of the chart in pixels (creates the "donut hole")
`width` | Number | null (element width) | Override the width of the chart
`height` | Number | null (element height) | Override the height of the chart
`delimiter` | String | "/" | The delimiter between the values

#### Line Chart Options

Option | Type | Default | Description
--- | --- | --- | ---
`delimiter` | String | "," | The delimiter between the values
`fill` | String | "#c6d9fd" | The color of the area beneath the line
`height` | Number | 16 | The height of the chart in pixels
`max` | Number | null (auto) | The maximum value of the y-axis
`min` | Number | 0 | The minimum value of the y-axis
`stroke` | String | "#4d89f9" | The color of the line
`strokeWidth` | Number | 1 | The thickness of the line in pixels
`width` | Number | 32 | The width of the chart in pixels

#### Bar Chart Options

Option | Type | Default | Description
--- | --- | --- | ---
`delimiter` | String | "," | The delimiter between the values
`fill` | Array | ["#4d89f9"] | The colors of the bars (positive, negative)
`height` | Number | 16 | The height of the chart in pixels
`max` | Number | null (auto) | The maximum value of the y-axis
`min` | Number | 0 | The minimum value of the y-axis
`padding` | Number | 0.1 | The padding between bars as a fraction of the bar width
`width` | Number | 32 | The width of the chart in pixels

Pro Tip: When using Peity with SmartAdmin, leverage CSS variables in your chart colors for consistent theming across light and dark modes.

## Advanced Usage

#### Custom Colors with SmartAdmin Theme

    // Use SmartAdmin CSS variables for consistent colors
    import { PeityAPI } from './thirdparty/peity/peity.es6.js';

    document.addEventListener('DOMContentLoaded', function() {
        // Create pie charts with primary colors
        document.querySelectorAll('.peity-pie-primary').forEach(element => {
            PeityAPI.create(element, 'pie', {
                fill: ['var(--primary-500)', 'var(--primary-200)'],
                radius: 20
            });
        });

        // Create donut charts with success colors
        document.querySelectorAll('.peity-donut-success').forEach(element => {
            PeityAPI.create(element, 'donut', {
                fill: ['var(--success-500)', 'var(--gray-300)'],
                innerRadius: 15,
                radius: 30
            });
        });

        // Create line charts with info colors
        document.querySelectorAll('.peity-line-info').forEach(element => {
            PeityAPI.create(element, 'line', {
                fill: 'var(--info-200)',
                stroke: 'var(--info-500)',
                width: 100,
                height: 30
            });
        });
    });

#### Data Updates

Peity charts can be updated dynamically to reflect new data:

    // Get the chart element
    const updatingElement = document.querySelector('.updating-chart');
    const values = updatingElement.textContent.split(',').map(Number);

    // Create the chart
    const chart = PeityAPI.create(updatingElement, 'line', {
        width: 100,
        height: 30,
        stroke: 'var(--info-500)',
        fill: 'var(--info-200)'
    });

    // Update the chart with new data
    setInterval(function() {
        const random = Math.round(Math.random() * 10);
        values.shift();
        values.push(random);

        updatingElement.textContent = values.join(',');
        chart.draw(); // Redraw the chart with new data
    }, 1000);

#### Using in Tables

    <table class="table table-striped">
        <thead>
            <tr>
                <th>Project</th>
                <th>Progress</th>
                <th>Trend</th>
                <th>Status</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Website Redesign</td>
                <td><span class="peity-pie">3/8</span></td>
                <td><span class="peity-line">5,3,9,6,5,9,7</span></td>
                <td><span class="badge bg-success">Active</span></td>
            </tr>
            <tr>
                <td>Mobile App</td>
                <td><span class="peity-pie">7/8</span></td>
                <td><span class="peity-line">3,5,6,8,2,5,9</span></td>
                <td><span class="badge bg-warning">Pending</span></td>
            </tr>
        </tbody>
    </table>

    <script type="module">
        // The charts will be automatically initialized by peitycharts.js
        // No additional code needed if using the built-in classes
    </script>

#### Global Defaults

Set global defaults for all Peity charts of a specific type:

    // Import the PeityAPI
    import { PeityAPI } from './thirdparty/peity/peity.es6.js';

    // Set defaults for all pie charts
    PeityAPI.defaults.pie = {
        delimiter: "/",
        fill: ["var(--primary-500)", "var(--gray-300)"],
        radius: 20
    };

    // Set defaults for all line charts
    PeityAPI.defaults.line = {
        delimiter: ",",
        fill: "var(--primary-200)",
        height: 20,
        min: 0,
        stroke: "var(--primary-500)",
        strokeWidth: 1,
        width: 80
    };

    // Now initialize charts (they'll use the new defaults)
    document.querySelectorAll('.peity-pie').forEach(element => {
        PeityAPI.create(element, 'pie');
    });

    document.querySelectorAll('.peity-line').forEach(element => {
        PeityAPI.create(element, 'line');
    });

## Further Resources

For more information about Peity charts in SmartAdmin:

- SmartAdmin ES6 Implementation: See the source files:
  - `src/scripts/pages/peitycharts.js` - Auto-initialization logic
  - `src/scripts/core/thirdparty/peity/peity.es6.js` - Core Peity implementation
- Original Peity Project (reference only): GitHub Repository

Note:

The SmartAdmin implementation is a custom ES6 version without jQuery dependency. The original jQuery-based Peity project is provided only as a reference. If you're looking for more complex charts and dashboards, consider other libraries included in SmartAdmin like ApexCharts or EasyPieChart.

Pro Tip: The SmartAdmin implementation adds extra features:

- Automatic chart type detection based on data format
- Smart color defaults that work with the theme system
- Support for CSS variables in all color properties
- Zero jQuery dependency for modern web applications

##### On This Page

- Introduction
- Installation
- Chart Types
- Configuration Options
- Advanced Usage
- Further Resources

#### Hi Sunny,

how can I help you today?
Analyze my data

Create a new report

Summarize my Calendar

App Builder
Unlock limitless design potential with 16+ layout combinations and extensive customization options—tailor your dashboard to fit your exact needs.
Header position fixed
Navigation full height
Navigation position fixed
Navigation collapsed
Navigation Minified
Dark Navigation
Colorblind Mode
High Contrast Mode