Skip to content

Commit 1789868

Browse files
tannerlinsleytannerlinsley
committed
docs: update
1 parent 066ba96 commit 1789868

File tree

18 files changed

+2061
-2026
lines changed

18 files changed

+2061
-2026
lines changed

‎docs/src/manifests/manifest.json

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,12 @@
1515
"editUrl": "/docs/installation.md"
1616
},
1717
{
18-
"title": "API Reference (WIP)",
18+
"title": "Getting Started",
19+
"path": "/docs/getting-started",
20+
"editUrl": "/docs/getting-started.md"
21+
},
22+
{
23+
"title": "API Reference",
1924
"path": "/docs/api",
2025
"editUrl": "/docs/api.md"
2126
}

‎docs/src/pages/docs/api.md

Lines changed: 105 additions & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -3,226 +3,165 @@ id: api
33
title: API
44
---
55

6-
> Complete documentation is **coming soon**. For now, please refer to the examples for any missing documentation.
6+
> 🚨 This documentation is for **Version 3.0.0, which is currently in beta and is a work-in-progress**. For now, please refer to the examples for any missing documentation.
77
88
## Memoize your Props!
99

10-
As you'll see in every example, the React Charts `<Chart>` component expects all props and options to be memoized using either `React.useMemo` or `React.useCallback`. While passing an unmemoized option/prop to the `<Chart>` component won't severly break any visible functionality, your charts will be severly non-performant. Internally, React Charts uses the immutable nature of these options/props to detect changes to the configuration and update accordingly.
11-
12-
While this may feel heavy at first, it gives you, the dev, full control over when you want to update your charts. To trigger and update, simply trigger one of your `React.useMemo` or `React.useCallback` hooks on the part of the config that you would like to update!
10+
The React Charts `<Chart>` component has a few options that need to be **stable** or **memoized using either `React.useMemo` or `React.useCallback`**. Using an unstable option incorrectly shouldn't severly break any basic functionality, but could results in infinite change-detection loops in your app or at the very least, your charts will be severly non-performant. If an option says it needs to be stable, it's not kidding around!
1311

1412
## Data Model
1513

1614
React Charts uses a data shape based on **arrays of series and nested arrays of datums in those series**.
1715

1816
```js
19-
// series array
2017
const data = [
2118
{
22-
// individual series
2319
label: 'Purchases',
24-
// datum array
2520
data: [
2621
{
27-
// individual datum
28-
primary: 'Apples', // primary value
29-
secondary: 20, // secondary value
22+
date: new Date(),
23+
stars: 299320,
3024
},
25+
// ...etc
3126
],
3227
},
3328
]
3429
```
3530

3631
Visualization data can come in practically any shape and size, so **memoization of data into this shape is almost always necessary**.
3732

38-
```javascript
39-
function MyChart() {
40-
const data = React.useMemo(
41-
() => [
42-
{
43-
label: 'Series 1',
44-
data: [
45-
{ primary: 1, secondary: 10 },
46-
{ primary: 2, secondary: 10 },
47-
{ primary: 3, secondary: 10 },
48-
],
49-
},
50-
{
51-
label: 'Series 2',
52-
data: [
53-
{ primary: 1, secondary: 10 },
54-
{ primary: 2, secondary: 10 },
55-
{ primary: 3, secondary: 10 },
56-
],
57-
},
58-
{
59-
label: 'Series 3',
60-
data: [
61-
{ primary: 1, secondary: 10 },
62-
{ primary: 2, secondary: 10 },
63-
{ primary: 3, secondary: 10 },
64-
],
65-
},
66-
],
67-
[]
68-
)
69-
70-
const axes = React.useMemo(
71-
() => [
72-
{ primary: true, type: 'linear', position: 'bottom' },
73-
{ type: 'linear', position: 'left' },
74-
],
75-
[]
76-
)
77-
78-
return (
79-
<div
80-
style={{
81-
width: '400px',
82-
height: '300px',
83-
}}
84-
>
85-
<Chart data={data} axes={axes} />
86-
</div>
87-
)
88-
}
33+
```tsx
34+
const data = React.useMemo(
35+
() => [
36+
{
37+
label: 'Series 1',
38+
data: [
39+
// ...
40+
],
41+
},
42+
{
43+
label: 'Series 2',
44+
data: [
45+
// ...
46+
],
47+
},
48+
{
49+
label: 'Series 3',
50+
data: [
51+
// ...
52+
],
53+
},
54+
],
55+
[]
56+
)
8957
```
9058

59+
The individual datums in a series' `data` array can be anything you want! Just remember that most of the types for React Query will require you to pass the type of your `Datum`s as the first generic type to work correctly.
60+
9161
## Axes
9262

93-
React Charts supports an `axes` prop that handles both the underlying scale and visual rendering of all axes. Multiple axes can be combined and configured to plot data however you'd like.
63+
React Charts uses axes to configure a fair amount of the chart. Axes handle many things like:
64+
65+
- Accessing chart values from your series' `Datum`s
66+
- Positioning your axis on the grid
67+
- Configuring the scale type for your axis
68+
- Configuring the element type for series that are tied to your axis
9469

9570
To date, we have the following scale types available:
9671

9772
- `linear` - A continuous axis used for plotting numerical data on an evenly distributed scale. Works well both as a **primary and secondary** axis.
98-
- `ordinal` - A banded axis commonly used to plot categories or ordinal information. Works well as the **primary** axis for bar charts.
99-
- `time` - A continuous axis used for plotting localized times and dates on an evenly distributed scale. Works well as a **primary** axis.
100-
- `utc` - Similar to the `time` scale, but supports UTC datetimes instead of localized datetimes. Works well as a **primary** axis.
73+
- `band` - A banded axis commonly used to plot categories or ordinal information. Works well as the **primary** axis for bar charts with ordinal domains.
74+
- `time` - A continuous axis used for plotting UTC `Date`s on an evenly distributed scale. Works well as a **primary** axis.
75+
- `timeLocal` - Similar to the `time` scale, but uses localized `Date` objects instead of UTC. Works well as a **primary** axis.
10176
- `log` - A continuous axis used for plotting numerical data on a logarithmically distributed scale. Works well as a **secondary** axis
10277

103-
Axes are a required component of a React Chart and can used like so:
78+
Axes are a required component of a React Chart. Both a `primaryAxis` and at least one axis vis `secondaryAxes` must be configured.
10479

10580
```javascript
10681
import { Chart } from 'react-charts'
10782

83+
type MyDatum = { date: Date, stars: number }
84+
10885
function MyChart() {
109-
const axes = React.useMemo(
110-
() => [
111-
{ primary: true, type: 'time', position: 'bottom' },
112-
{ type: 'linear', position: 'left' },
86+
const data = [
87+
{
88+
label: 'React Charts',
89+
data: [
90+
{
91+
date: new Date(),
92+
stars: 23467238,
93+
},
94+
],
95+
},
96+
]
97+
98+
const primaryAxis = React.useMemo(
99+
(): AxisOptions<MyDatum> => ({
100+
isPrimary: true,
101+
scaleType: 'time',
102+
position: 'bottom',
103+
getValue: datum => datum.date,
104+
}),
105+
[]
106+
)
107+
108+
const secondaryAxes = React.useMemo(
109+
(): AxisOptions<MyDatum>[] => [
110+
{
111+
scaleType: 'linear',
112+
position: 'left',
113+
getValue: datum => datum.stars,
114+
},
113115
],
114116
[]
115117
)
116118

117119
return (
118-
<div
119-
style={{
120-
width: '400px',
121-
height: '300px',
120+
<Chart
121+
options={{
122+
data,
123+
primaryAxis,
124+
secondaryAxes,
122125
}}
123-
>
124-
<Chart axes={axes} />
125-
</div>
126+
/>
126127
)
127128
}
128129
```
129130

130-
## Series Types
131+
## Secondary Axis Element Types
132+
133+
Secondary axes can be configured to render their respective series using 3 different element types using the `AxisOptions<TDatum>['scaleType']` property:
131134

132-
- Cartesian
133-
- `line`
134-
- `area`
135-
- `bar`
136-
- `bubble`
137-
- Radial
138-
- `pie`
135+
- `line`
136+
- 1 Line per series (optional, eg. for Bubble/Scatter charts)
137+
- 1 Circle per datum (optional)
138+
- `area`
139+
- 1 Enclosed area per series
140+
- 1 Line per series (optional)
141+
- 1 Circle per datum (optional)
142+
- `bar`
143+
- 1 Rectangle per datum
139144

140145
Example
141146

142147
```javascript
143-
function MyChart() {
144-
const series = React.useMemo(() => ({ curve: 'cardinal' }), [])
145-
146-
return <Chart series={series} />
147-
}
148+
const secondaryAxes = React.useMemo(
149+
(): AxisOptions<MyDatum>[] => [
150+
{
151+
// scaleType: 'linear',
152+
// position: 'left',
153+
// getValue: datum => datum.stars,
154+
elementType: 'bar',
155+
},
156+
],
157+
[]
158+
)
148159
```
149160

150-
# API
161+
### Curve Types
151162

152-
**`<Chart />` Props**
153-
154-
- `series({} or function)` - A `memoized` object (or function that returns an object) of series options that correspond to all or each of the series in the dataset.
155-
`type` - **string** - The series type (Line, Bar, Bubble, Area, etc)
156-
`showPoints` - **bool** - If true, will show points for datums where applicable
157-
`showOrphans` - **bool** - If true, will show orphan datums where applicable
158-
`curve` - **func** - The curve function to use for this series where applicable (see [Curve Types](#curve-types))
159-
- `axes[]` - An array of `memoized` axes
160-
- `axis{}` - An axis object
161-
- `primary` **bool** - Denotes whether this axis is the primary axis
162-
- `type` **oneOf, required** - The type of scale for this axis
163-
- `ordinal`
164-
- `time`
165-
- `utc`
166-
- `linear`
167-
- `log`
168-
- `position` **oneOf, required** - The cartesian position of this axis
169-
- `top`
170-
- `right`
171-
- `bottom`
172-
- `left`
173-
- `invert` **bool** - Whether this axis's scale should be inverted
174-
- `primaryAxisID` **string** - If multiple primary axes are used, which primary axis ID does this axis refer to?
175-
- `min` **number** - The suggested minimum for this axis
176-
- `max` **number** - The suggested maximum for this axis
177-
- `hardMin` **number** - The hard/forced minimum for this axis
178-
- `hardMax` **number** - The hard/forced maximum for this axis
179-
- `base` **number** - The base value for this axis. Defaults to `0`
180-
- `ticks` **function** - The function used to generate ticks for the axis
181-
- `format` **func** - The function used to format values on this axis for display
182-
- `tickValues` **any** - The optional override for the tick values of the axis
183-
- `tickSizeInner` **number** - The size of inner tick lines for the axis
184-
- `tickSizeOuter` **number** - The size of the outer tick lines for the axis
185-
- `tickPadding` **number** - The padding amount between tick labels
186-
- `maxLabelRotation` **number** - The max label rotation angle in degrees. Defaults to 50
187-
- `innerPadding` **number** - The inner padding for the axis
188-
- `outerPadding` **number** - The outer padding for the axis
189-
- `showGrid` **bool** - Whether or not the axis grid lines should be visible
190-
- `showTicks` **bool** - Whether or not the tick and tick labels should be visible
191-
- `show` **bool** - Whether or not the axis and scale are visible
192-
- `stacked` **bool** - If true, will use stacked mode
193-
- `id` **any** - An optional ID to identify this axis
194-
- `primaryCursor{}` - An object of options for the primary cursor. If falsey, the cursor is disabled
195-
- `render` - **func** - The render function for this cursor. Returns JSX
196-
- `snap` - **bool** - If true, the cursor will snap to nearest values on the axis
197-
- `showLine` - **bool** - If true, will show the grid line for this cursor
198-
- `showLabel` - **bool** - If true, will show the label for this cursor
199-
- `axisID` - **any** - The ID of the axis that this cursor corresponds to
200-
- `onChange` - **func** - When the cursor is updated, this function will be called with relevant information
201-
- `tooltip{}`
202-
`align` - **
203-
`alignPriority**`- **arrayOf**(alignPropType),`padding`- **number**,`tooltipArrowPadding`- **number**,`anchor`- **oneOf**([`anchorPointer`,`anchorClosest`,`anchorCenter`,`anchorTop`,`anchorBottom`,`anchorLeft`,`anchorRight`,`anchorGridTop`,`anchorGridBottom`,`anchorGridLeft`,`anchorGridRight`]),`render`- **func**.required,`onChange` - **func**
163+
All element types that support lines or curves can be configured by passing any `curve` generator function as the `AxisOptions<TDatum>['curve']` option. By default, horizontal and vertical series default to using `monotoneX` and `monotoneY` curves, respectively. More information can be found at [`d3-shape curves`](https://github.com/d3/d3-shape#curves)
204164

205-
### Curve Types
165+
# API
206166

207-
All series types that support lines or curves can be configured to use any [curve function from `d3-shape`](https://github.com/d3/d3-shape#curves) by passing one of the following strings as the `curve` prop to a series component. You may also pass your own curve function directly from d3 or if you're feeling powerful, even create your own!
208-
209-
Note the following string correspond to their respective d3 curve functions but with the `curve` prefix removed.
210-
211-
- `basisClosed`
212-
- `basisOpen`
213-
- `basis`
214-
- `bundle`
215-
- `cardinalClosed`
216-
- `cardinalOpen`
217-
- `cardinal`
218-
- `catmullRomClosed`
219-
- `catmullRomOpen`
220-
- `catmullRom`
221-
- `linearClosed`
222-
- `linear`
223-
- `monotoneX` (default)
224-
- `monotoneY`
225-
- `natural`
226-
- `step`
227-
- `stepAfter`
228-
- `stepBefore`
167+
> Coming Soon! Feel free to consult the **[examples](/examples/simple)** or refer to the exported types in your favorite IDE for now.

0 commit comments

Comments
 (0)