import {Meta} from '@storybook/addon-docs/blocks';
import Logo from "./Logo.jsx";
import HomeChart from "./HomeChart.jsx";

<Meta title="Introduction" />

<Logo />

<div style={{
  textAlign: "center",
  maxWidth: "550px",
  margin: "0 auto 4rem"
}}>

# Data visualization made easy.

An open-source TypeScript library that extends [D3](https://d3js.org/) to create beautiful, interactive SVG visualizations with minimal configuration. Tooltips, color assignments, label placements, and more — all handled automatically.

</div>

<HomeChart />


## 20+ Chart Types

D3plus ships with a wide variety of chart types, all accessible through a simple configuration object:

<div style={{
  display: "grid",
  gridTemplateColumns: "repeat(auto-fill, minmax(140px, 1fr))",
  gap: "0.5rem",
  margin: "1rem 0 2rem"
}}>
  {[
    "Area Plot", "Bar Chart", "Box & Whisker", "Bump Chart",
    "Donut", "Geomap", "Line Plot", "Matrix",
    "Network", "Pack", "Pie", "Priestley",
    "Radar", "Radial Matrix", "Rings", "Sankey",
    "Stacked Area", "Tree", "Treemap"
  ].map(name => (
    <div key={name} style={{
      padding: "0.5rem 0.75rem",
      borderRadius: "6px",
      border: "1px solid var(--sb-borderColor, #e0e0e0)",
      fontSize: "0.85rem",
      textAlign: "center"
    }}>
      {name}
    </div>
  ))}
</div>

Explore each chart type in the **Core > Charts** section of the sidebar.


## Getting Started (React)

Install the React wrapper package:

```sh
npm install @d3plus/react
```

Pass a configuration object to the `config` prop of any visualization component:

```jsx
import {Treemap} from "@d3plus/react";

const config = {
  data: [
    {id: "alpha", value: 29},
    {id: "beta",  value: 10}
  ],
  groupBy: "id",
  size: "value"
};

<Treemap config={config} />
```

Set shared defaults across all visualizations using the `D3plusContext` Provider. Per-component `config` props override globals on a key-by-key basis via deep merge.

```jsx
import React from "react";
import ReactDOM from "react-dom/client";
import {D3plusContext} from "@d3plus/react";
import App from "src/App.jsx";

const globalConfig = {
  title: "Shared Title for All Visualizations"
};

ReactDOM.createRoot(document.getElementById("viz")).render(
  <React.StrictMode>
    <D3plusContext.Provider value={globalConfig}>
      <App />
    </D3plusContext.Provider>
  </React.StrictMode>
);
```

## Vanilla JavaScript (CDN)

Load the core bundle directly via a script tag:

```html
<script src="https://cdn.jsdelivr.net/npm/@d3plus/core"></script>
```

Then use the global `d3plus` object:

```html
<script>
  new d3plus.Treemap()
    .config({
      data: [
        {id: "alpha", value: 29},
        {id: "beta",  value: 10}
      ],
      groupBy: "id",
      size: "value"
    })
    .render();
</script>
```


## Packages

D3plus is a modular monorepo. Install only what you need:

| Package | Description |
|---------|-------------|
| [@d3plus/react](https://www.npmjs.com/package/@d3plus/react) | React component wrappers for all chart types |
| [@d3plus/core](https://www.npmjs.com/package/@d3plus/core) | Charts, components, and shapes (the main engine) |
| [@d3plus/color](https://www.npmjs.com/package/@d3plus/color) | Color scales, defaults, and utilities |
| [@d3plus/data](https://www.npmjs.com/package/@d3plus/data) | Data loading, filtering, and manipulation |
| [@d3plus/dom](https://www.npmjs.com/package/@d3plus/dom) | DOM and browser utility functions |
| [@d3plus/export](https://www.npmjs.com/package/@d3plus/export) | SVG and image export |
| [@d3plus/format](https://www.npmjs.com/package/@d3plus/format) | Number and date formatting |
| [@d3plus/locales](https://www.npmjs.com/package/@d3plus/locales) | Translation dictionaries for i18n |
| [@d3plus/math](https://www.npmjs.com/package/@d3plus/math) | Math and geometry utilities |
| [@d3plus/text](https://www.npmjs.com/package/@d3plus/text) | Text measurement, wrapping, and fitting |
| [@d3plus/types](https://www.npmjs.com/package/@d3plus/types) | Unified TypeScript type definitions |

For example, to use just the number formatting utilities:

```sh
npm install @d3plus/format
```

---

```js
import {formatAbbreviate} from "@d3plus/format";
```

To get all d3plus types in one import (useful for typing config objects or function parameters):

```sh
npm install @d3plus/types
```

---

```ts
import type {Treemap, D3plusComponentProps} from "@d3plus/types";
```


## Accessibility

D3plus is built with accessibility in mind. Every visualization automatically includes ARIA attributes, semantic roles, and contextual labels for screen readers. Additional features include:

- **`role="img"`** on all SVG containers, with optional `<title>` and `<desc>` elements
- **Contextual `aria-label`** attributes on every shape, tailored per chart type (e.g. rank and value for Treemap, x/y coordinates for Plot)
- **Inline data tables** for screen readers via the `ariaHidden` configuration
- **Color contrast utilities** that automatically select legible text colors against any background
- **Localization** of all accessible text and number formatting across multiple locales

See the **Accessibility** page in the sidebar for full details, including a WCAG 2.1 AA conformance summary.


## Built with D3plus

<div style={{
  display: "grid",
  gridTemplateColumns: "repeat(auto-fill, minmax(200px, 1fr))",
  gap: "0.5rem",
  margin: "1rem 0"
}}>
  {[
    {name: "OEC.world", url: "https://oec.world/"},
    {name: "Data USA", url: "https://datausa.io/"},
    {name: "DataSaudi", url: "https://datasaudi.sa/"},
    {name: "COTEC Spain", url: "https://complejidadeconomica.cotec.es/"},
    {name: "Puerto Rico Family Data Center", url: "https://data.youthpr.org/en"},
    {name: "Data Africa", url: "https://dataafrica.io/"},
    {name: "CDC AR&PSP", url: "https://arpsp.cdc.gov/"},
    {name: "Healthy Communities NC", url: "https://healthycommunitiesnc.org/"},
    {name: "CNY Vitals Pro", url: "https://pro.cnyvitals.org/"},
    {name: "DataMPE Brasil", url: "https://datampe.sebrae.com.br/"},
    {name: "Estonia Statistics", url: "https://data.stat.ee/profile/country/ee/"},
  ].map(site => (
    <a
      key={site.name}
      href={site.url}
      target="_blank"
      rel="noopener noreferrer"
      style={{
        display: "block",
        padding: "0.6rem 0.75rem",
        borderRadius: "6px",
        border: "1px solid var(--sb-borderColor, #e0e0e0)",
        fontSize: "0.85rem",
        textAlign: "center",
        textDecoration: "none",
        color: "inherit"
      }}
    >
      {site.name}
      <span style={{display: "block", fontSize: 10, lineHeight: 1, marginBottom: 5}}>{site.url}</span>
    </a>
  ))}
</div>

