npm package: @huzaifawaqar/charts-redefined
Description: A modern, aesthetic, and efficient charting library.
Author: Huzaifa Waqar
Latest version: 0.0.1

# Charts Redefined

A modern, highly customizable, and responsive React charting library built on top of D3.js. Designed for creating beautiful dashboards with minimal configuration while offering deep customization options for advanced use cases.

## Features

- 🚀 **Built on D3.js**: Performance and mathematical precision.
- ⚛️ **React First**: Composition-based API (similar to Recharts).
- 🎨 **Beautiful Defaults**: Gradients, Glow effects, and Modern aesthetics out of the box.
- 📱 **Responsive**: Auto-scaling axes and layout logic.
- 🛠 **Deep Customization**: Control curves, strokes, fills, patterns, and more.
- 📊 **Advanced Visuals**: 3D Ribbon/Surface charts, Organic Radar charts, Gauge variants.

## Installation

```bash
npm install @huzaifawaqar/charts-redefined
```

## Quick Start

Here is a simple example of a responsive Area Chart with a time-scale X-Axis.

```tsx
import React from "react";
import {
  ChartContainer,
  AreaChart,
  XAxis,
  YAxis,
  Tooltip,
} from "@huzaifawaqar/charts-redefined";

const data = [
  { date: "2023-01-01", value: 400 },
  { date: "2023-01-02", value: 300 },
  { date: "2023-01-03", value: 550 },
  { date: "2023-01-04", value: 480 },
];

const MyChart = () => (
  <ChartContainer height={300} data={data}>
    <XAxis
      dataKey="date"
      scale="time"
      tickFormat={(d) => new Date(d).toLocaleDateString()}
    />
    <YAxis tickFormat={(v) => `$${v}`} />
    <Tooltip />
    <AreaChart xKey="date" yKey="value" color="#8884d8" showMarkers={true} />
  </ChartContainer>
);
```

---

## Core Components

### `ChartContainer`

The wrapper component that provides context (dimensions, scales, data) to all child components.

| Prop     | Type               | Default       | Description                                             |
| -------- | ------------------ | ------------- | ------------------------------------------------------- |
| `height` | `number \| string` | `400`         | Height of the chart area. Can be pixels or percentages. |
| `data`   | `any[]`            | `[]`          | Global data array accessible by all children.           |
| `margin` | `object`           | `{top:20...}` | Margins for axes labels.                                |
| `theme`  | `string`           | `'light'`     | Optional theme override.                                |

### `XAxis` & `YAxis`

Define the coordinate system.

| Prop         | Type                           | Component | Description                      |
| ------------ | ------------------------------ | --------- | -------------------------------- |
| `dataKey`    | `string`                       | **XAxis** | Key in data object for X values. |
| `scale`      | `'band' \| 'time' \| 'linear'` | **XAxis** | Type of scale to use.            |
| `tickFormat` | `(val: any) => string`         | **Both**  | Function to format tick labels.  |
| `ticks`      | `number[]`                     | **Both**  | Optional manual ticks array.     |

---

## Chart Types

### AreaChart

Filled line chart, useful for trends.

| Prop          | Type                         | Default          | Description               |
| ------------- | ---------------------------- | ---------------- | ------------------------- |
| `data`        | `any[]`                      | Context          | Data to plot.             |
| `xKey`        | `string`                     | required         | X-axis key.               |
| `yKey`        | `string`                     | required         | Y-axis key.               |
| `color`       | `string`                     | `var(--primary)` | Fill color.               |
| `gradient`    | `{from: string, to: string}` | `undefined`      | Optional gradient fill.   |
| `showMarkers` | `boolean`                    | `false`          | Show dots on data points. |

### BarChart

Basic Bar Chart. For Stacked or Grouped, see dedicated components below.

| Prop       | Type                         | Default      | Description                                          |
| ---------- | ---------------------------- | ------------ | ---------------------------------------------------- |
| `layout`   | `'vertical' \| 'horizontal'` | `'vertical'` | Orientation of bars.                                 |
| `radius`   | `number`                     | `4`          | Border radius of bars.                               |
| `gradient` | `object`                     | `undefined`  | `{ from, to, direction }`                            |
| `glow`     | `boolean`                    | `false`      | Adds an SVG filter glow effect.                      |
| `pattern`  | `object`                     | `undefined`  | Apply stripe/check patterns (`{ type: 'stripes' }`). |

### LineChart

Standard line chart with curve interpolation support.

| Prop          | Type              | Default             | Description                                    |
| ------------- | ----------------- | ------------------- | ---------------------------------------------- |
| `strokeWidth` | `number`          | `2`                 | Thickness of the line.                         |
| `curve`       | `d3.CurveFactory` | `d3.curveMonotoneX` | Interpolation function (e.g., `d3.curveStep`). |

# Advanced Charts

### StackedBarChart

Display multiple series stacked on top of each other.

| Prop     | Type                         | Default      | Description                                            |
| -------- | ---------------------------- | ------------ | ------------------------------------------------------ |
| `keys`   | `string[]`                   | required     | Array of keys to stack (e.g. `['revenue', 'profit']`). |
| `colors` | `string[]`                   | `[...]`      | Colors corresponding to keys.                          |
| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Chart orientation.                                     |

### GroupedBarChart

Display multiple series side-by-side.

| Prop           | Type       | Default  | Description                                |
| -------------- | ---------- | -------- | ------------------------------------------ |
| `keys`         | `string[]` | required | Array of keys to group.                    |
| `groupPadding` | `number`   | `0.2`    | Padding between groups (0-1).              |
| `barPadding`   | `number`   | `0.05`   | Padding between bars within a group (0-1). |

### RangeBarChart

Display min/max intervals (floating bars).

| Prop      | Type                  | Default  | Description                         |
| --------- | --------------------- | -------- | ----------------------------------- |
| `minKey`  | `string`              | required | Key for minimum value.              |
| `maxKey`  | `string`              | required | Key for maximum value.              |
| `variant` | `'bar' \| 'dumbbell'` | `'bar'`  | Style: Solid bar or line-with-dots. |
| `glow`    | `boolean`             | `false`  | Glow effect.                        |

### PieChart / DonutChart

Circular Proportions. `DonutChart` is a PieChart with a default innerRadius.

| Prop           | Type     | Default   | Description                |
| -------------- | -------- | --------- | -------------------------- |
| `valueKey`     | `string` | required  | Key for segment size.      |
| `labelKey`     | `string` | optional  | Key for legend/tooltip.    |
| `innerRadius`  | `number` | `0` (Pie) | Radius of inner hole.      |
| `padAngle`     | `number` | `0.02`    | Space between slices.      |
| `cornerRadius` | `number` | `4`       | Rounded corners of slices. |

### GaugeChart (Speedometer)

A highly configurable gauge for single-value metrics.

| Prop         | Type                                | Default    | Description                                                     |
| ------------ | ----------------------------------- | ---------- | --------------------------------------------------------------- |
| `value`      | `number`                            | required   | Current value.                                                  |
| `min`        | `number`                            | `0`        | Minimum scale value.                                            |
| `max`        | `number`                            | `100`      | Maximum scale value.                                            |
| `variant`    | `'simple' \| 'segments' \| 'ticks'` | `'simple'` | Visual style of the gauge track.                                |
| `segments`   | `GaugeSegment[]`                    | `[]`       | Array of `{ limit: number, color: string }` for colorful zones. |
| `showNeedle` | `boolean`                           | `false`    | Render a pointer needle.                                        |
| `startAngle` | `number`                            | `-90`      | Start angle in degrees.                                         |
| `endAngle`   | `number`                            | `90`       | End angle in degrees.                                           |

### RadarChart

Useful for comparing multiple variables.

| Prop          | Type                                     | Default    | Description                              |
| ------------- | ---------------------------------------- | ---------- | ---------------------------------------- |
| `radiusKeys`  | `string[]`                               | required   | Array of keys to plot (multiple series). |
| `angleKey`    | `string`                                 | required   | Key for the labels around the perimeter. |
| `curveType`   | `'linear' \| 'cardinal' \| 'catmullRom'` | `'linear'` | Smoothness of the polygon shape.         |
| `fillOpacity` | `number`                                 | `0.3`      | Opacity of the filled area.              |

### RadialBarChart

Circular bar chart (Apple Watch style).

| Prop          | Type     | Default  | Description               |
| ------------- | -------- | -------- | ------------------------- |
| `valueKey`    | `string` | required | Key for value.            |
| `labelKey`    | `string` | required | Label for ring.           |
| `innerRadius` | `number` | `50`     | Radius of innermost ring. |
| `barSize`     | `number` | `12`     | Thickness of bars.        |
| `startAngle`  | `number` | `0`      | Start angle.              |
| `endAngle`    | `number` | `360`    | End angle (max arc).      |

### ScatterChart

Plot separate points.

| Prop       | Type     | Default  | Description       |
| ---------- | -------- | -------- | ----------------- |
| `xKey`     | `string` | required | X Coordinate.     |
| `yKey`     | `string` | required | Y Coordinate.     |
| `labelKey` | `string` | optional | Tooltip label.    |
| `dotSize`  | `number` | `6`      | Radius of points. |

### BubbleChart

Scatter chart where point size represents a third dimension (Z).

| Prop        | Type     | Default  | Description                      |
| ----------- | -------- | -------- | -------------------------------- |
| `zKey`      | `string` | required | Key for bubble size.             |
| `minRadius` | `number` | `4`      | Pixel radius for smallest value. |
| `maxRadius` | `number` | `30`     | Pixel radius for largest value.  |

### HeatmapChart

Grid-based intensity visualization.

| Prop       | Type       | Default         | Description                                 |
| ---------- | ---------- | --------------- | ------------------------------------------- |
| `xKey`     | `string`   | required        | Column category.                            |
| `yKey`     | `string`   | required        | Row category.                               |
| `valueKey` | `string`   | required        | Intensity value.                            |
| `colors`   | `string[]` | `[green range]` | Array of 2+ colors for interpolation scale. |
| `gap`      | `number`   | `2`             | Gap between cells.                          |

### StackedAreaChart

Area chart with accumulated values.

| Prop     | Type              | Default     | Description        |
| -------- | ----------------- | ----------- | ------------------ |
| `keys`   | `string[]`        | required    | Keys to stack.     |
| `colors` | `string[]`        | `[...]`     | Colors for layers. |
| `curve`  | `d3.CurveFactory` | `monotoneX` | Interpolation.     |

### StreamGraph

Organic, flowing stacked graph centered around the axis.

| Prop     | Type                       | Default    | Description                            |
| -------- | -------------------------- | ---------- | -------------------------------------- |
| `offset` | `'wiggle' \| 'silhouette'` | `'wiggle'` | Offset algorithm for the stream shape. |
| `keys`   | `string[]`                 | required   | Series keys.                           |

### Ribbon3DChart (Matrix)

A pseudo-3D surface chart created by stacking offset layers.

| Prop          | Type                     | Default        | Description                                             |
| ------------- | ------------------------ | -------------- | ------------------------------------------------------- |
| `data`        | `RibbonLayer[]`          | required       | Array containing `{ z: number, values: {x,y}[] }`.      |
| `depthOffset` | `{x: number, y: number}` | `{x:10, y:10}` | Pixel offset per Z-index unit to create depth illusion. |

# Financial & Statistical Charts

### CandlestickChart

OHLC (Open-High-Low-Close) financial chart.

| Prop        | Type     | Default   | Description              |
| ----------- | -------- | --------- | ------------------------ |
| `openKey`   | `string` | required  | Open price.              |
| `highKey`   | `string` | required  | High price.              |
| `lowKey`    | `string` | required  | Low price.               |
| `closeKey`  | `string` | required  | Close price.             |
| `bullColor` | `string` | `emerald` | Color when Close > Open. |
| `bearColor` | `string` | `red`     | Color when Close < Open. |

### BoxPlotChart

Statistical distribution summary (Min, Q1, Median, Q3, Max).

| Prop        | Type     | Default  | Description       |
| ----------- | -------- | -------- | ----------------- |
| `minKey`    | `string` | required | 0th Percentile.   |
| `q1Key`     | `string` | required | 25th Percentile.  |
| `medianKey` | `string` | required | 50th Percentile.  |
| `q3Key`     | `string` | required | 75th Percentile.  |
| `maxKey`    | `string` | required | 100th Percentile. |

## Styling

The library uses CSS Variables for easy theming. You can override these in your global CSS:

```css
:root {
  --chart-primary: #3b82f6;
  --chart-secondary: #8b5cf6;
  --chart-tertiary: #10b981;
  --chart-grid-color: #e5e7eb;
  --chart-axis-text: #6b7280;
  --chart-tooltip-bg: rgba(255, 255, 255, 0.95);
}

.dark {
  --chart-grid-color: #1e293b;
  --chart-axis-text: #94a3b8;
  --chart-tooltip-bg: rgba(15, 23, 42, 0.95);
}
```

## License

MIT