> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jtbdos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# D3js PRAWN

> Next‑generation predictive chart component built on D3

# D3js PRAWN Line Chart

PRAWN stands for **Predictive, Real‑time, Automatic, Workflow Navigator**.  The goal of every PRAWN component is to visually demonstrate how your application is *getting the job done* for the user (in the Clayton Christensen *Jobs‑to‑Be‑Done* sense) and, more importantly, **how well** it is doing so.

The `LineChart` component does this by combining traditional time‑series visualisation with forward‑looking *predictions* and on‑chart editing.  Users can quickly see where things are headed, adjust expectations, and understand the factors driving outcomes – all without leaving the context of the dashboard.

> 🦐 **Why “PRAWN”?**  Much like its shell‑fish namesake, a PRAWN component should be small, tasty and easy to consume.  The acronym captures its four core principles:

* **Predictive** – includes built‑in forecast lines (expected, optimistic & pessimistic)
* **Real‑time** – updates as soon as fresh data arrives
* **Automatic** – sensible defaults mean zero configuration for common use‑cases
* **Workflow Navigator** – makes it obvious what action the user should take next

## Quick start

```tsx
import { LineChart } from '@repo/design-system/components/d3js-prawn/line-chart';

const { data, prediction } = generateSampleData(12, true, true); // helper from utils

export default function Example() {
  return (
    <LineChart
      data={data}
      prediction={prediction}
      title="Weekly Revenue"
      yLabel="USD ($)"
      showGrid
      showLatestValue
      latestValueTitle="Latest revenue"
    />
  );
}
```

## Props

| Name              | Type                                 | Default     | Description                                                                   |
| ----------------- | ------------------------------------ | ----------- | ----------------------------------------------------------------------------- |
| `data`            | `DataPoint[]`                        | —           | Required data set. Each point contains `x`, `y`, and optional `currency` keys |
| `prediction`      | `Prediction \| MultiPointPrediction` | `undefined` | Expected/optimistic/pessimistic forecast lines                                |
| `width`           | `number`                             | `800`       | Width in pixels                                                               |
| `height`          | `number`                             | `400`       | Height in pixels                                                              |
| `showGrid`        | `boolean`                            | `true`      | Toggles background grid                                                       |
| `showLatestValue` | `boolean`                            | `false`     | Show sticky latest‑point label                                                |
| `lineColor`       | `string`                             | `#2563eb`   | Primary line colour                                                           |
| `theme`           | `'light' \| 'dark'`                  | `'light'`   | Pre‑set colour themes                                                         |

Refer to the full type definition in `utils/types.ts` for advanced options like drag‑to‑edit predictions, custom date formats and currency symbols.

## Tour integration

All PRAWN components support the `Tour` overlay so you can guide first‑time users through the metrics that matter:

```tsx
import type { TourStep } from '@repo/design-system/components/ui/tour';

const steps: TourStep[] = [
  { id: 'prawn-chart', title: 'Trend', description: 'Shows historical revenue' },
  { id: 'prawn-prediction', title: 'Forecast', description: 'Machine‑generated projection' },
];

<LineChart data={data} prediction={prediction} tourSteps={steps} />;
```