Skip to content

Commit

Permalink
Merge pull request airbnb#23 from Flaque/docs
Browse files Browse the repository at this point in the history 
Add Shape docs
  • Loading branch information
@hshoff
hshoff authored May 14, 2017
2 parents 7fef319 + fcdeb8b commit a76675e
Showing 1 changed file with 200 additions and 0 deletions.
200 changes: 200 additions & 0 deletions packages/vx-shape/Readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,206 @@
# @vx/shape

Shapes are the core elements of vx. Most of what you see on the screen, like lines, bars, and areas are shapes.

## `<AreaClosed />`

AreaClosed is a closed area under a curve.

### Example
![AreaClosed Example](http://i.imgur.com/hT0q8qx.png)

``` js
<Shape.AreaClosed
data={myData}
xScale={myXScale}
yScale={myYScale}
x={myX}
y={myY}
strokeWidth={2}
stroke={'url(#linear)'}
fill={'url(#linear)'}
/>
```

### Properties

| Name | Default | Type | Description |
|:--------------- |:------------------- |:-------- |:----------------------------------------------------------------------------------------------------------- |
| x | | function | A function that takes in a data element and returns the x value. |
| y | | function | A function that takes in a data element and returns the y value. |
| xScale | | function | A [scale function](https://github.com/hshoff/vx/tree/master/packages/vx-scale) for the xs. |
| yScale | | function | A [scale function](https://github.com/hshoff/vx/tree/master/packages/vx-scale) for the ys. |
| data | | array | An array of x and y data. |
| defined | `d => y(d) && x(d)` | function | A [function](https://github.com/d3/d3-shape/blob/master/README.md#area_defined) called by `area.defined()`. |
| className | `vx-area-closed` | string | The class name for the `path` element. |
| strokeDasharray | | array | The [pattern of dashes](https://mzl.la/1l7EiTQ) in the stroke. |
| strokeWidth | 2 | number | The size of the stroke. |
| stroke | black | string | The color of the stroke. |
| fill | rgba(0,0,0,0.3) | string | The color of the fill. |
| curve | | function | The [curve function](https://github.com/hshoff/vx/tree/master/packages/vx-curve) |

## `<AreaStack />`

An `<AreaStack />` is used to represent several area's stacked on top of each other.

### Example
![AreaStack Example](http://i.imgur.com/Gh930t7.png)

``` js
<Shape.AreaStack
reverse
top={margin.top}
left={margin.left}
keys={keys}
data={data}
x={(d) => xScale(x(d.data))}
y0={(d) => yScale(d[0] / 100)}
y1={(d) => yScale(d[1] / 100)}
stroke={(d,i) => colorScale(i)}
strokeWidth={1}
fillOpacity={(d,i) => selected.includes(browserNames[i]) ? 0.8 : 0.2}
fill={(d,i) => colorScale(i)}
onMouseEnter={(d, i) => event => {
updateSelected((prevState) => ([browserNames[i]]))
}}
onMouseLeave={(d,i) => event => {
updateSelected(prevState => {
if (prevState.includes(browserNames[i])) return [];
return prevState;
})
}}
/>
```

### Properties

| Name | Default | Type | Description |
|:--------- |:------- |:-------- |:----------------------------------------------------------------------------------------------------------- |
| className | | string | The class name for the `path` element. |
| top | 0 | number | The margin on top. |
| left | 0 | number | The margin on the left. |
| keys | | array | Keys for the [d3.stack.](https://github.com/d3/d3-shape/blob/master/README.md#stack) |
| data | | array | The data for each stack. |
| curve | | function | The [curve function](https://github.com/hshoff/vx/tree/master/packages/vx-curve) |
| defined | | function | A [function](https://github.com/d3/d3-shape/blob/master/README.md#area_defined) called by `area.defined()`. |
| x | | function | The d3 [x function.](https://github.com/d3/d3-shape#area_x) |
| x0 | | function | The d3 [x0 function.](https://github.com/d3/d3-shape#area_x0) |
| x1 | | function | The d3 [x1 function.](https://github.com/d3/d3-shape#area_x1) |
| y0 | | function | The d3 [y0 function.](https://github.com/d3/d3-shape#area_y0) |
| y1 | | function | The d3 [y1 function.](https://github.com/d3/d3-shape#area_y1) |
| glyph | | glyph | [A glyph](https://github.com/hshoff/vx/tree/master/packages/vx-glyph) to be added to the stack. |
| reverse | false | bool | If true, reverses the order of stacks. |

## `<Bar />`

A simple rectangle (a `<rect>` element) to use in your graphs.

### Example

![bar example](http://i.imgur.com/pvV9BJU.png)

``` js
<Shape.Bar
width={xScale.bandwidth()}
height={barHeight}
x={xScale(x(d))}
y={yMax - barHeight}
fill="url('#lines')"
stroke={'black'}
strokeWidth={1}
/>
```

### Properties

| Name | Default | Type | Description |
|:---------------- |:--------- |:------ |:-------------------------------------------------------------- |
| className | | string | The class name for the `path` element. |
| x | 0 | number | A number or function for the x coordinate. |
| y | 0 | number | A number or function for the y coordinate. |
| width | | number | The pixel width of the bar. |
| height | | number | The pixel height of the bar. |
| rx | | number | The pixel value of the corner radius. |
| ry | | number | The pixel value of the corner radius. |
| fill | steelblue | string | The color for the fill of the rect element. |
| fillOpacity | | number | The opacity for the fill of the rect element |
| stroke | | string | The color for the stroke of the rect element. |
| strokeWidth | | number | The pixel width of the stroke. |
| strokeDasharray | | array | The [pattern of dashes](https://mzl.la/1l7EiTQ) in the stroke. |
| strokeLinecap | | string | The svg [linecap](https://mzl.la/2pM1786) of the stroke. |
| strokeLinejoin | | string | The svg [linejoin](https://mzl.la/2pzdxEB) of the stroke. |
| strokeMiterlimit | | number | The svg [Miterlimit](https://mzl.la/2pLVE13) of the stroke. |
| strokeOpacity | | number | The svg opacity. |

## `<Line />`

A simple line. Good for drawing in the sand.

### Example

``` js
<Shape.Line
from={new Point({x:0, y:3})}
to={new Point({x:0, y:10})}
/>
```

### Properties

| Name | Default | Type | Description |
|:--------------- |:------------------------ |:------ |:----------------------------------------------------------------------------------------- |
| from | new Point({ x: 0 y: 0 }) | Point | The beginning [point](https://github.com/hshoff/vx/tree/master/packages/vx-point). |
| to | new Point({ x: 1 y: 1 }) | Point | The end [point](https://github.com/hshoff/vx/tree/master/packages/vx-point). |
| stroke | black | string | The color of the stroke. |
| strokeWidth | 1 | number | The pixel width of the stroke. |
| strokeDasharray | | array | The [pattern of dashes](https://mzl.la/1l7EiTQ) in the stroke. |
| transform | | string | An [SVG transform.](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform) |
| className | | string | The class name for the `line` element. |


## `<LinePath />`

A more complicated line path. A `<LinePath />` is useful for making line graphs and drawing.

### Example

![Linepath example](http://i.imgur.com/YoDZrGi.png)

``` js
<Shape.LinePath
data={dataset[1].data}
xScale={xScale}
yScale={yScale}
x={x}
y={y}
stroke={"black"}
strokeWidth={2}
/>
```

### Properties

| Name | Default | Type | Description |
|:--------------- |:------------ |:-------- |:----------------------------------------------------------------------------------------------------------- |
| data | | array | The data in x, y. |
| xScale | | function | A [scale function](https://github.com/hshoff/vx/tree/master/packages/vx-scale) for the xs. |
| yScale | | function | A [scale function](https://github.com/hshoff/vx/tree/master/packages/vx-scale) for the ys. |
| x | | function | A function that takes in a data element and returns the x value. |
| y | | function | A function that takes in a data element and returns the y value. |
| defined | | function | A [function](https://github.com/d3/d3-shape/blob/master/README.md#line_defined) called by `line.defined()`. |
| className | | string | The class name for the `path` element. |
| stroke | steelblue | string | The color of the stroke. |
| strokeWidth | 2 | number | The pixel value for the stroke. |
| strokeDasharray | | array | The [pattern of dashes](https://mzl.la/1l7EiTQ) in the stroke. |
| fill | none | string | The color of the fill for the `path` element. |
| curve | Curve.linear | function | The [curve function](https://github.com/hshoff/vx/tree/master/packages/vx-curve) |
| glyph | | glyph | [A glyph](https://github.com/hshoff/vx/tree/master/packages/vx-glyph) to be added to the line. |


## Sources For Components
+ [`<AreaClosed />`](https://github.com/hshoff/vx/blob/master/packages/vx-shape/src/shapes/AreaClosed.js)
+ [`<AreaStack />`](https://github.com/hshoff/vx/blob/master/packages/vx-shape/src/shapes/AreaStack.js)
+ [`<Bar />`](https://github.com/hshoff/vx/blob/master/packages/vx-shape/src/shapes/Bar.js)
+ [`<Line />`](https://github.com/hshoff/vx/blob/master/packages/vx-shape/src/shapes/Line.js)
+ [`<LinePath />`](https://github.com/hshoff/vx/blob/master/packages/vx-shape/src/shapes/LinePath.js)

Expand Down

0 comments on commit a76675e

Please sign in to comment.