# glance-charts 📊

`glance-charts` is an ultra-lightweight (under **8KB** gzipped), high-performance, and accessible data visualization library with zero dependencies. It supports native vector graphics styled with standard CSS, high-frequency canvas rendering, and 3D projections.

---

## ⚡ Key Features

*   **Zero Dependencies**: Pure vanilla JavaScript and CSS.
*   **Featherweight Footprint**: Under **8KB gzipped** — loads instantly on any connection.
*   **Dual Engine Architecture**: Automatically selects crisp vector **SVG** for graphics and falls back to **Canvas** for high-frequency datasets (>2000 points).
*   **Beautiful by Default**: Features modern Outfit typography, glassmorphism tooltips, responsive sizing, and subtle animations.
*   **Accessible & SEO Friendly**: Semantic tags and labels are screen-reader accessible and indexable by search engines.
*   **Universal Export**: One-click download menu to export charts as vector **SVG** or raw **CSV** files.

---

## 🚀 Installation & Setup

### Via NPM
```bash
npm install glance-charts
```

### Via CDN (jsDelivr)
Include the stylesheet and scripts directly in your HTML header:
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/glance-charts/glance-charts.css">
<script src="https://cdn.jsdelivr.net/npm/glance-charts/glance-charts.js"></script>
```

---

## 🛠️ Initialization API

Initialize a chart by calling the global `Glance` factory wrapper or instantiating the `GlanceChart` class:

```javascript
// Functional Initialization (Recommended)
const chart = Glance(containerSelector, config);

// Class Initialization
const chart = new GlanceChart(containerSelector, config);
```

### Parameters
*   `containerSelector` (string): The CSS selector of the container element (e.g., `'#chart'`).
*   `config` (object): The configuration object containing elements, dataset arrays, and custom options.

---

## 📈 Supported Chart Types (29 Elements)

### 📊 Standard Cartesian (6)
*   **Line Chart (`line`)** — Smooth cubic-bezier lines with optional gradient fills.
*   **Bar Chart (`bar`)** — Vertical columns with customizable spacing and rounded caps.
*   **Horizontal Bar (`horizontalBar`)** — Left-to-right bar layout.
*   **Pie Chart (`pie`)** — Proportional segment wedges.
*   **Donut Chart (`doughnut` or `donut`)** — Modern ring layout supporting center text labels.
*   **Area Chart (`area`)** — Shaded area charts for cumulative progression.

### 🧪 Advanced & Statistical (7)
*   **Scatter Plot (`scatter`)** — High-frequency correlation plots.
*   **Bubble Chart (`bubble`)** — Correlation plots with independent coordinate radius.
*   **Radar Chart (`radar`)** — Webbed concentric polygons.
*   **Polar Area (`polarArea` or `polar`)** — Concentric circle wedges with variable radii.
*   **Box Plot (`boxplot`)** — 5-point distributions (Min, Q1, Median, Q3, Max) with outliers.
*   **Violin Plot (`violin`)** — KDE probability distribution bell curves.
*   **Candlestick (`candlestick`)** — Financial open-high-low-close (OHLC) candles.

### 🥞 Stacked Variations (3)
*   **Stacked Bar (`stackedBar`)** — Segmented vertical bar stacks.
*   **Stacked Horizontal Bar (`stackedHBar`)** — Segmented horizontal bar stacks.
*   **Stacked Area (`stackedArea`)** — Layered area segments showing cumulative parts.

### 🌀 Specialized Visualizations (9)
*   **Heatmap (`heatmap`)** — Color-encoded density matrices.
*   **Treemap (`treemap`)** — Hierarchical rectangular partitions.
*   **Gauge (`gauge`)** — 180° speedometer dials with custom indicators.
*   **Funnel Chart (`funnel`)** — Progressive acquisition conversion stages.
*   **Waterfall Chart (`waterfall`)** — Running balance sheets showing additions/subtractions.
*   **Sunburst Chart (`sunburst`)** — Concentric layered hierarchical structures.
*   **Sankey Diagram (`sankey`)** — Bezier flow ribbon diagrams.
*   **Word Cloud (`wordcloud`)** — Archimedean-spiral text scaling.
*   **Vector Map (`map`)** — Continental outline maps.

### 🔌 Utility HTML Widgets (3)
*   **KPI Card (`kpi`)** — High-impact indicators with custom trends and sparklines.
*   **Data Table (`table`)** — Responsive database tables.
*   **Text Box (`text`)** — Styled comment boxes for annotations.

---

## 💻 Code Examples

### 1. Cartesian Line Chart
```javascript
Glance('#my-chart', {
    type: 'line',
    data: {
        labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
        datasets: [{
            label: 'Visits',
            data: [12, 19, 3, 25, 17],
            color: '#6366f1',
            fill: true
        }]
    }
});
```

### 2. Speedometer Gauge
```javascript
Glance('#my-gauge', {
    type: 'gauge',
    data: {
        datasets: [{
            data: [72], // Current position
            color: '#ef4444' // Indicator needle color
        }]
    },
    options: {
        min: 0,
        max: 100,
        title: 'Processor Load'
    }
});
```

### 3. KPI Card Widget (HTML-rendered)
```javascript
Glance('#my-kpi', {
    type: 'kpi',
    trend: '+15.2%',
    data: {
        labels: ['Active Users'],
        datasets: [{
            data: [1420],
            sparklineData: [1100, 1250, 1380, 1420],
            color: '#10b981'
        }]
    }
});
```

---

## 🎨 Theme Customization (CSS Variables)

Customize the charts globally or container-wise using CSS variables:

```css
:root {
    --glance-font: 'Outfit', sans-serif;
    --glance-bg: transparent;
    --glance-grid: #e2e8f0;            /* Gridlines color */
    --glance-text: #64748b;            /* Legend & Axis text color */
    --glance-tooltip-bg: rgba(255, 255, 255, 0.9);
    --glance-tooltip-border: #e2e8f0;
    --glance-tooltip-text: #0f172a;
}
```

---

## License
MIT