Skip to content

Commit 32daae3

Browse files
fritz-cfritz-c
committed
docs: start improving documentation
1 parent 73823cf commit 32daae3

File tree

1 file changed

+110
-0
lines changed

1 file changed

+110
-0
lines changed

‎README.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,90 @@ Simple shape editor component
44

55
[![CircleCI](https://circleci.com/gh/fritz-c/react-shape-editor.svg?style=svg)](https://circleci.com/gh/fritz-c/react-shape-editor)
66

7+
## Components
8+
9+
### ShapeEditor
10+
11+
The wrapper for the entire editor component. Contains the `<svg>` element.
12+
13+
| Prop | Type | Default | <div style="width: 400px;">Description</div> |
14+
| :------------ | :-----------------: | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
15+
| children | renderable elements | `null` | Will include components such as `wrapShape`-wrapped shapes, other library components (`SelectionLayer`/`ImageLayer`/`DrawLayer`) or arbitrary SVG elements |
16+
| focusOnAdd | `bool` | `true` | If `true`, focus on newly created elements. |
17+
| focusOnDelete | `bool` | `true` | If `true`, focus on the next-closest element after a shape is deleted. |
18+
| scale | `number` | `1` | Scale factor of the svg contents. For example, given a `vectorWidth` of `100` and a scale of `0.5`, the rendered DOM element will be 50 px wide. |
19+
| style | `object` | `{}` | Style to apply to the `<svg>` element. |
20+
| vectorHeight | `number` | `0` | Height of the `<svg>` element viewBox. |
21+
| vectorWidth | `number` | `0` | Width of the `<svg>` element viewBox. |
22+
23+
---
24+
25+
### ImageLayer
26+
27+
Renders an svg image element.
28+
29+
| Prop | Type | Default | <div style="width: 400px;">Description</div> |
30+
| :------------------- | :------: | :------: | :-------------------------------------------------------------------------------------------------- |
31+
| src<br/>_(required)_ | `string` | | URL for the image to display. |
32+
| onLoad | `func` | `()=>{}` | Callback for the image load. Signature: `({ naturalWidth: number, naturalHeight: number }) => void` |
33+
34+
---
35+
36+
### wrapShape (HOC)
37+
38+
When used to wrap an SVG element, enables resize and movement functionality.
39+
40+
**Usage**
41+
42+
```js
43+
const WrappedRect = wrapShape(({ height, width /* ... "wrapShape Props Received" */ }) => (
44+
<rect fill="blue" height={height} width={width} />
45+
))
46+
47+
// later, in render()
48+
49+
<WrappedRect
50+
shapeId={myId}
51+
x={12}
52+
y={56}
53+
width={20}
54+
/* ... "WrappedShape Props" */
55+
/>
56+
```
57+
58+
**wrapShape Props Received**
59+
60+
| Prop | Type | <div style="width: 400px;">Description</div> |
61+
| :------------- | :------: | :--------------------------------------------------------------------------------------------------------------------------------------------- |
62+
| height | `number` | Height of the shape. |
63+
| width | `number` | Width of the shape. |
64+
| disabled | `bool` | If `true`, the shape cannot be moved or resized, and shows no resize handles. |
65+
| isBeingChanged | `bool` | If `true`, the shape is currently being moved or scaled. |
66+
| scale | `number` | Scale of the parent `<svg>` element, provided so you can render strokes or other components that maintain a constant size at every zoom level. |
67+
68+
**WrappedShape Props**
69+
70+
| Prop | Type | Default | <div style="width: 400px;">Description</div> |
71+
| :-------------------------- | :---------: | :-------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
72+
| height<br/>_(required)_ | `number` | | Height of the shape. |
73+
| shapeId<br/>_(required)_ | `string` | | Unique identifier for the shape, to aid in data handling. |
74+
| width<br/>_(required)_ | `number` | | Width of the shape. |
75+
| x<br/>_(required)_ | `number` | | x-axis offset of the shape. |
76+
| y<br/>_(required)_ | `number` | | y-axis offset of the shape. |
77+
| active | `bool` | `false` | If `true`, the shape is rendered as focused (particularly important when using a `SelectionLayer`). When not using a selection layer, this prop can be left unset, as native HTML focus will handle focus state. |
78+
| constrainMove | `func` | non-constraining function | A callback for restricting movement during shape transformations (e.g., to lock movement to one axis or snap it to a grid). Signature: `({ originalX: number, originalY: number, x: number, y: number, width: number, height: number }) => ({ x: number, y: number })` |
79+
| constrainResize | `func` | non-constraining function | A callback for restricting resizing during shape transformations (e.g., to lock resizing to one axis or snap it to a grid). Signature: `({ originalMovingCorner: { x: number, y: number }, startCorner: { x: number, y: number }, movingCorner: { x: number, y: number }, lockedDimension: one of "x" or "y" }) => ({ x: number, y: number })` |
80+
| disabled | `bool` | `false` | If `true`, the shape cannot be moved or resized, and shows no resize handles. |
81+
| isInSelectionGroup | `bool` | `false` | |
82+
| keyboardTransformMultiplier | `number` | `0` | |
83+
| onBlur | `func` | `0` | |
84+
| onChange | `func` | `0` | |
85+
| onDelete | `func` | `0` | |
86+
| onFocus | `func` | `0` | |
87+
| onKeyDown | `func` | `0` | |
88+
| ResizeHandleComponent | `Component` | [`DefaultResizeHandleComponent`](src/DefaultResizeHandleComponent.js) | |
89+
| wrapperProps | `object` | `{}` | |
90+
791
## Usage
892

993
```jsx
@@ -117,3 +201,29 @@ export default class Editor extends React.Component {
117201
}
118202
}
119203
```
204+
205+
## Contributing
206+
207+
After cloning the repository and running `npm install` inside, you can use the following commands to develop and build the project.
208+
209+
```sh
210+
# Starts a dev server that hosts a demo page with the component.
211+
npm start
212+
213+
# Runs the library tests
214+
npm test
215+
216+
# Lints the code with eslint
217+
npm run lint
218+
219+
# Lints and builds the code, placing the result in the dist directory.
220+
# This build is necessary to reflect changes if you're
221+
# `npm link`-ed to this repository from another local project.
222+
npm run build
223+
```
224+
225+
Pull requests are welcome!
226+
227+
## License
228+
229+
MIT

0 commit comments

Comments
 (0)