Skip to content

Commit 7c6bd0b

Browse files
adamwoodnzadamwoodnz
committed
Add docs
1 parent 30860b3 commit 7c6bd0b

File tree

3 files changed

+322
-2
lines changed

3 files changed

+322
-2
lines changed

‎projects/js-packages/charts/src/components/geo-chart/stories/index.api.mdx‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
import { Meta } from '@storybook/addon-docs/blocks';
2+
3+
<Meta title="JS Packages/Charts/Types/Geo Chart/API Reference" />
4+
5+
# Geo Chart API Reference
6+
7+
## GeoChart
8+
9+
Main component for rendering geographical data on an interactive world map.
10+
11+
**Props:**
12+
13+
| Prop | Type | Default | Description |
14+
| ---- | ---- | ------- | ----------- |
15+
| `data` | `Record<string, number>` | - | **Required.** Record mapping country ISO codes (e.g., 'USA', 'CAN', 'GBR') to numeric values |
16+
| `width` | `number` | - | **Required.** Width of the chart in pixels |
17+
| `height` | `number` | - | **Required.** Height of the chart in pixels |
18+
| `className` | `string` | - | Additional CSS class name for the chart container |
19+
| `chartId` | `string` | - | Custom chart identifier for accessibility |
20+
21+
## GeoChartProps Type
22+
23+
```typescript
24+
interface GeoChartProps extends Pick<BaseChartProps, 'className' | 'data' | 'chartId' | 'width' | 'height'> {}
25+
```
26+
27+
## FeatureShape Type
28+
29+
Internal type representing a geographic feature in the map topology.
30+
31+
```typescript
32+
interface FeatureShape {
33+
type: 'Feature';
34+
id: string;
35+
geometry: {
36+
coordinates: [number, number][][];
37+
type: 'Polygon';
38+
};
39+
properties: {
40+
name: string;
41+
};
42+
}
43+
```
44+
45+
## TooltipData Type
46+
47+
Internal type for tooltip data structure.
48+
49+
```typescript
50+
interface TooltipData {
51+
countryName: string;
52+
countryId: string;
53+
value: number;
54+
}
55+
```
56+
57+
## Theme Properties
58+
59+
The following properties can be customized via the theme system:
60+
61+
| Property | Type | Default | Description |
62+
| -------- | ---- | ------- | ----------- |
63+
| `colors[0]` | `string` | `'#069E08'` | Primary color used for data visualization with alpha transparency |
64+
| `backgroundColor` | `string` | `'#FFFFFF'` | Background color of the map |
65+
| `geoChart.countryFillColor` | `string` | `'#E5E7EB'` | Fill color for countries without data values |
66+
67+
## Country ISO Codes
68+
69+
The `data` prop accepts three-letter ISO 3166-1 alpha-3 country codes. Common examples:
70+
71+
- **USA**: United States
72+
- **CAN**: Canada
73+
- **GBR**: United Kingdom
74+
- **DEU**: Germany
75+
- **FRA**: France
76+
- **JPN**: Japan
77+
- **AUS**: Australia
78+
- **BRA**: Brazil
79+
- **IND**: India
80+
- **CHN**: China
81+
- **MEX**: Mexico
82+
- **ESP**: Spain
83+
- **ITA**: Italy
84+
- **NLD**: Netherlands
85+
- **RUS**: Russia
86+
- **KOR**: South Korea
87+
- **ZAF**: South Africa
88+
- **NGA**: Nigeria
89+
- **ARG**: Argentina
90+
- **SAU**: Saudi Arabia
91+
92+
For a complete list, refer to the ISO 3166-1 alpha-3 standard.
93+
94+
## Map Projection
95+
96+
The chart uses **Mercator projection** from `@visx/geo` with the following parameters:
97+
98+
- **Scale**: Calculated as `width * 0.16`
99+
- **Translation**: `[centerX, centerY + 50]` (slightly offset vertically)
100+
- **Topology**: World country boundaries from Natural Earth data
101+
102+
## Color Scaling
103+
104+
Colors are automatically scaled using `@visx/scale`'s `scaleLinear`:
105+
106+
- **Domain**: `[0, maxValue]` where maxValue is the highest value in the data
107+
- **Range**: `[lightColor, fullColor]` where lightColor has 20% opacity (hex: `#RRGGBB20`)
108+
- **Interpolation**: Linear interpolation between transparent and full opacity
109+

‎projects/js-packages/charts/src/components/geo-chart/stories/index.docs.mdx‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
import { Meta, Canvas, Story, Source } from '@storybook/addon-docs/blocks';
2+
import * as GeoChartStories from './index.stories';
3+
4+
<Meta title="JS Packages/Charts/Types/Geo Chart" of={ GeoChartStories } />
5+
6+
# Geo Chart
7+
8+
Geo Charts visualize geographical data on an interactive world map using Mercator projection, making it easy to understand the distribution of values across countries.
9+
10+
<Canvas of={ GeoChartStories.Default } />
11+
12+
## Overview
13+
14+
The Geo Chart component provides a clean, accessible solution for displaying country-level data on a world map. Built on `@visx/geo` with Mercator projection, it supports interactive tooltips, automatic color scaling, and integration with the chart theme system:
15+
16+
<Source
17+
language="tsx"
18+
code={ `import { GeoChart } from '@automattic/charts';
19+
20+
<GeoChart
21+
data={ ordersByCountry }
22+
width={ 800 }
23+
height={ 500 }
24+
/>` }
25+
/>
26+
27+
## API Reference
28+
29+
For detailed information about component props and types, see the [Geo Chart API Reference](./?path=/docs/js-packages-charts-types-geo-chart-api-reference--docs).
30+
31+
## Basic Usage
32+
33+
### Simple Geo Chart
34+
35+
The simplest geo chart requires data, width, and height. The `data` prop accepts a record mapping country ISO codes to numeric values:
36+
37+
<Canvas of={ GeoChartStories.Default } />
38+
39+
<Source
40+
language="tsx"
41+
code={ `<GeoChart
42+
data={ {
43+
USA: 1000,
44+
CAN: 500,
45+
GBR: 450,
46+
DEU: 400,
47+
AUS: 350,
48+
FRA: 300,
49+
MEX: 250,
50+
JPN: 200,
51+
BRA: 150,
52+
IND: 120,
53+
} }
54+
width={ 800 }
55+
height={ 500 }
56+
/>` }
57+
/>
58+
59+
### Required Props
60+
61+
- **`data`**: Record mapping country ISO codes (e.g., 'USA', 'CAN', 'GBR') to numeric values
62+
- **`width`**: Width of the chart in pixels
63+
- **`height`**: Height of the chart in pixels
64+
65+
### Optional Props
66+
67+
- **`className`**: Additional CSS class name for custom styling
68+
69+
For detailed prop information and type definitions, see the [Geo Chart API Reference](./?path=/docs/js-packages-charts-types-geo-chart-api-reference--docs).
70+
71+
## Interactive Features
72+
73+
### Hover Tooltips
74+
75+
The Geo Chart includes built-in interactive tooltips that display on hover, showing:
76+
77+
- Country name
78+
- Country ISO code
79+
- Value for that country
80+
81+
Tooltips are automatically enabled and positioned near the cursor for optimal readability.
82+
83+
### Color Scaling
84+
85+
The chart automatically scales colors based on data values:
86+
87+
- **No data**: Countries without values use the default theme color
88+
- **Low values**: Displayed with lighter, semi-transparent colors
89+
- **High values**: Displayed with full opacity using the primary theme color
90+
91+
The color scale uses alpha transparency (20% to 100% opacity) for smooth gradations that maintain visual consistency across different themes.
92+
93+
## Country Code Format
94+
95+
The Geo Chart uses three-letter ISO country codes (ISO 3166-1 alpha-3). Common examples:
96+
97+
- **USA**: United States
98+
- **CAN**: Canada
99+
- **GBR**: United Kingdom
100+
- **DEU**: Germany (Deutschland)
101+
- **FRA**: France
102+
- **JPN**: Japan
103+
- **AUS**: Australia
104+
- **BRA**: Brazil
105+
- **IND**: India
106+
- **CHN**: China
107+
- **MEX**: Mexico
108+
- **ESP**: Spain
109+
- **ITA**: Italy
110+
- **NLD**: Netherlands
111+
112+
**Important**: Use the three-letter codes (alpha-3), not two-letter codes. For a complete list of country codes, refer to the [ISO 3166-1 alpha-3 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).
113+
114+
## Styling and Customization
115+
116+
### Theme Integration
117+
118+
Geo Charts automatically integrate with the chart theme system for colors and styling:
119+
120+
<Source
121+
language="tsx"
122+
code={ `import { GlobalChartsProvider, jetpackTheme } from '@automattic/charts';
123+
124+
<GlobalChartsProvider theme={ jetpackTheme }>
125+
<GeoChart
126+
data={ ordersByCountry }
127+
width={ 800 }
128+
height={ 500 }
129+
/>
130+
</GlobalChartsProvider>` }
131+
/>
132+
133+
The chart uses the following theme properties:
134+
135+
- **`colors[0]`**: Primary color for data visualization (used with alpha transparency for scaling)
136+
- **`backgroundColor`**: Background color for the map
137+
- **`geoChart.countryFillColor`**: Fill color for countries without data
138+
139+
### Custom Styling
140+
141+
Add custom styles using the `className` prop:
142+
143+
<Source
144+
language="tsx"
145+
code={ `.custom-geo-chart {
146+
border-radius: 8px;
147+
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
148+
}
149+
150+
<GeoChart
151+
data={ ordersByCountry }
152+
width={ 800 }
153+
height={ 500 }
154+
className="custom-geo-chart"
155+
/>` }
156+
/>
157+
158+
## Map Projection Details
159+
160+
The Geo Chart uses Mercator projection with the following characteristics:
161+
162+
- **Projection**: Standard Mercator (equirectangular-like distortion)
163+
- **Center**: Slightly offset vertically (50px down) for better visual balance
164+
- **Scale**: Automatically calculated as `width * 0.16` for optimal sizing
165+
- **Graticule**: Hidden by default (grid lines set to transparent)
166+
167+
This projection provides a familiar world map layout suitable for most geographical data visualization needs.
168+
169+
## Best Practices
170+
171+
### Data Preparation
172+
173+
- **Use correct ISO codes**: Ensure country codes follow the three-letter ISO 3166-1 alpha-3 format
174+
- **Validate data**: Check that values are positive numbers
175+
- **Consider scale**: Large value ranges will show more dramatic color differences
176+
177+
### Performance Considerations
178+
179+
The Geo Chart renders efficiently for typical use cases, but consider these factors:
180+
181+
- **Fixed dimensions**: The chart uses fixed width and height, not responsive sizing
182+
- **Tooltip rendering**: Tooltips are lightweight and render only on hover
183+
- **Map complexity**: The world topology is pre-loaded and optimized for performance
184+
185+
### Accessibility
186+
187+
- **Alternative views**: Consider providing a data table or list view for users who prefer non-visual data
188+
- **Color contrast**: The automatic color scaling maintains theme consistency, but test with your specific color choices
189+
- **Keyboard navigation**: Currently, the chart is primarily mouse-driven; consider complementing with keyboard-accessible data views
190+
191+
## Accessibility
192+
193+
### Mouse Interaction
194+
195+
- **Hover**: Move the mouse over any country to see its data in a tooltip
196+
- **Visual feedback**: Countries with data show graduated colors based on value magnitude
197+
198+
### Screen Reader Support
199+
200+
The Geo Chart currently uses standard SVG rendering without additional ARIA labels. For better accessibility:
201+
202+
- Provide a data table or list alongside the chart
203+
- Use descriptive headings to introduce the geographical data
204+
- Consider adding `aria-label` or `aria-describedby` to the container element
205+
206+
### Focus Management
207+
208+
The chart does not currently implement keyboard navigation. For full accessibility:
209+
210+
- Complement the chart with a keyboard-accessible data table
211+
- Provide text summaries of key insights
212+
- Consider using the chart as a visual supplement to accessible data presentations

‎projects/js-packages/charts/src/components/geo-chart/stories/index.stories.tsx‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ const meta: Meta< StoryArgs > = {
1616
parameters: {
1717
layout: 'centered',
1818
},
19-
tags: [ 'autodocs' ],
19+
decorators: [ chartDecorator ],
2020
argTypes: {
2121
data: {
2222
control: 'object',
@@ -51,7 +51,6 @@ const meta: Meta< StoryArgs > = {
5151
...sharedChartArgTypes,
5252
...themeArgTypes,
5353
},
54-
decorators: [ chartDecorator ],
5554
};
5655

5756
export default meta;

0 commit comments

Comments
 (0)