Skip to content

Commit 7f36b4d

Browse files
nasdannasdan
committed
add docs and examples
1 parent 319b41e commit 7f36b4d

File tree

21 files changed

+27412
-30572
lines changed

21 files changed

+27412
-30572
lines changed

‎docs/api/focal-point.mdx

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: FocalPoint
3+
---
4+
5+
The `FocalPoint` is the TypeScript interface that represents the focal point X and Y coordinates in percentage.
6+
7+
:::note
8+
9+
You can see the default value in [Props section](image-focal-point/#props).
10+
11+
:::
12+
13+
## Interface
14+
15+
```typescript
16+
export interface FocalPoint {
17+
x: number;
18+
y: number;
19+
}
20+
```
21+
22+
## Example of use
23+
24+
The following example shows how to use the `FocalPoint` interface in a TypeScript project.
25+
26+
```tsx showLineNumbers
27+
import '@lemoncode/react-image-focal-point/style.css';
28+
import {
29+
ImageFocalPoint,
30+
// highlight-next-line
31+
FocalPoint,
32+
} from '@lemoncode/react-image-focal-point';
33+
34+
const App = () => {
35+
// highlight-next-line
36+
const [focalPoint, setFocalPoint] = useState<FocalPoint>({ x: 5, y: 10 });
37+
return (
38+
<ImageFocalPoint
39+
src="your-image-src"
40+
// highlight-next-line
41+
focalPoint={focalPoint}
42+
onChange={newFocalPoint => {
43+
// highlight-next-line
44+
setFocalPoint(newFocalPoint);
45+
}}
46+
/>
47+
);
48+
};
49+
```

‎docs/api/image-focal-point-props.mdx

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: ImageFocalPointProps
3+
---
4+
5+
The `ImageFocalPointProps` is the TypeScript interface used by the [ImageFocalPoint](image-focal-point) component.
6+
7+
:::note
8+
9+
You can see the default values in [Props section](image-focal-point/#props).
10+
11+
:::
12+
13+
## Interface
14+
15+
```typescript
16+
export interface ImageFocalPointProps {
17+
src: string;
18+
onChange: (focalPoint: FocalPoint) => void;
19+
focalPoint?: FocalPoint;
20+
alt?: string;
21+
labels?: LabelProps;
22+
className?: string;
23+
classes?: ClassesProps;
24+
}
25+
```
26+
27+
## Example of use
28+
29+
The intention of exporting this interface is to be able to use it in other components, for example as a wrapper. The following example shows how to use the `ImageFocalPointProps` interface in a TypeScript project.
30+
31+
```tsx title="wrapper.tsx" showLineNumbers
32+
import React from 'react';
33+
import {
34+
ImageFocalPoint,
35+
// highlight-next-line
36+
ImageFocalPointProps,
37+
} from '@lemoncode/react-image-focal-point';
38+
39+
// highlight-next-line
40+
interface Props extends ImageFocalPointProps {
41+
// Whatever you want to add
42+
title: string;
43+
}
44+
45+
const Wrapper: React.FC<Props> = props => {
46+
const { title, ...otherProps } = props;
47+
return (
48+
<>
49+
<h3>{title}</h3>
50+
<ImageFocalPoint {...otherProps} />
51+
</>
52+
);
53+
};
54+
```

‎docs/api/image-focal-point.mdx

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: ImageFocalPoint (Component)
3+
---
4+
5+
The ImageFocalPoint component is the main file of the library. It is a wrapper of the HTML image element that allows you to drag and drop the focal point button on the image.
6+
7+
## Internal HTML structure
8+
9+
```html
10+
<div class="root">
11+
<button class="focalPoint"></button>
12+
<img class="image" />
13+
</div>
14+
```
15+
16+
## Props
17+
18+
| Name | Type | Default | Required | Description |
19+
| ---------- | ----------------------------------------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
20+
| src | string | - | &check; | The image [source attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-src). |
21+
| onChange | (focalPoint: [FocalPoint](focal-point)) => void | - | &check; | Callback function that will be called when the user clicks on the focal point button and moves the cursor over the image. |
22+
| focalPoint | [FocalPoint](focal-point) | `{ x: 50, y: 50 }` | - | Initial focal point value in percentage. |
23+
| alt | string | - | - | The image [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-alt). |
24+
| labels | [LabelProps](#labelprops) | `{ focalPoint: 'Focal point'}` | - | Labels to be used in the component. |
25+
| className | string | - | - | CSS class name to be applied to the root element. |
26+
| classes | [ClassesProps](#classesprops) | - | - | CSS class names to be applied to the component elements. |
27+
28+
## LabelProps
29+
30+
| Name | Type | Default | Required | Description |
31+
| ---------- | ------ | ----------- | -------- | ------------------------------------------- |
32+
| focalPoint | string | Focal point | false | Label to be used in the focal point button. |
33+
34+
## ClassesProps
35+
36+
| Name | Type | Default | Required | Description |
37+
| ---------- | ------ | ------- | -------- | ------------------------------------------------------- |
38+
| root | string | - | false | CSS class name to be applied to the root element. |
39+
| focalPoint | string | - | false | CSS class name to be applied to the focal point button. |
40+
| image | string | - | false | CSS class name to be applied to the image element. |

‎docs/api/reference.mdx

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: API Reference
3+
---
4+
5+
This section documents the complete React Image Focal Point API.
6+
7+
## Top-level exports
8+
9+
### Components
10+
11+
- [ImageFocalPoint](image-focal-point): the _Component_.
12+
13+
### Types (for TypeScript support)
14+
15+
- [ImageFocalPointProps](image-focal-point-props): the Component's props.
16+
- [FocalPoint](focal-point): the focal point view model.
17+
18+
## Importing
19+
20+
Every section described above is a top-level export. You can import any of them like this:
21+
22+
### ES Modules
23+
24+
```js
25+
import { ImageFocalPoint } from '@lemoncode/react-image-focal-point';
26+
```
27+
28+
### CommonJS
29+
30+
```js
31+
const { ImageFocalPoint } = require('@lemoncode/react-image-focal-point');
32+
```

‎docs/examples/basic-with-apply.mdx

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Basic example, apply button
3+
---
4+
5+
This example is quite similar to the [basic example](basic), but instead of applying the changes real time, the user has to click on an 'apply' button to see the updates reflected.
6+
7+
## Live example
8+
9+
import Tabs from '@theme/Tabs';
10+
import TabItem from '@theme/TabItem';
11+
12+
<Tabs
13+
defaultValue="codesandbox"
14+
values={[
15+
{ label: 'Codesandbox', value: 'codesandbox' },
16+
{ label: 'Stackblitz', value: 'stackblitz' },
17+
]}
18+
>
19+
<TabItem value="stackblitz">
20+
<a
21+
target="_blank"
22+
href="https://stackblitz.com/github/Lemoncode/react-image-focal-point/tree/main/examples/basic-with-apply?embed=1&file=src%2Fapp.tsx"
23+
>
24+
<img
25+
src="https://developer.stackblitz.com/img/open_in_stackblitz.svg"
26+
alt="Edit on StackBlitz"
27+
title="Edit on StackBlitz"
28+
/>
29+
</a>
30+
<iframe
31+
src="https://stackblitz.com/github/Lemoncode/react-image-focal-point/tree/main/examples/basic-with-apply?embed=1&file=src%2Fapp.tsx"
32+
style={{ width: '100%', height: '500px', border: 0, borderRadius: '4px', overflow: 'hidden' }}
33+
></iframe>
34+
</TabItem>
35+
<TabItem value="codesandbox">
36+
<a
37+
target="_blank"
38+
href="https://codesandbox.io/s/github/Lemoncode/react-image-focal-point/tree/main/examples/basic-with-apply?file=/src/app.tsx"
39+
>
40+
<img
41+
src="https://codesandbox.io/static/img/play-codesandbox.svg"
42+
alt="Edit on Codesandbox"
43+
title="Edit on Codesandbox"
44+
/>
45+
</a>
46+
<iframe
47+
src="https://codesandbox.io/embed/github/Lemoncode/react-image-focal-point/tree/main/examples/basic-with-apply?fontsize=14&hidenavigation=1&module=%2Fsrc%2Fapp.tsx&theme=dark&view=editor"
48+
style={{ width: '100%', height: '500px', border: 0, borderRadius: '4px', overflow: 'hidden' }}
49+
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
50+
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
51+
></iframe>
52+
</TabItem>
53+
</Tabs>

‎docs/examples/basic.mdx

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: Basic
3+
---
4+
5+
Minimum example, here you can just drag the focal point and the example pictures focal point will be updated on real time.
6+
7+
## How to apply this feature in your code
8+
9+
Import the library styles and the component:
10+
11+
```jsx
12+
import '@lemoncode/react-image-focal-point/style.css';
13+
import { ImageFocalPoint } from '@lemoncode/react-image-focal-point';
14+
15+
const App = () => {
16+
return (
17+
18+
);
19+
}
20+
21+
```
22+
23+
Then use the component:
24+
25+
```diff
26+
import '@lemoncode/react-image-focal-point/style.css';
27+
import { ImageFocalPoint } from '@lemoncode/react-image-focal-point';
28+
29+
const App = () => {
30+
return (
31+
+ <ImageFocalPoint
32+
+ src="your-image-src"
33+
+ onChange={(focalPoint) => {
34+
+ // Whatever you want to do when the user clicks on the image
35+
+ }}
36+
+ />
37+
);
38+
}
39+
40+
```
41+
42+
## Live example
43+
44+
import Tabs from '@theme/Tabs';
45+
import TabItem from '@theme/TabItem';
46+
47+
<Tabs
48+
defaultValue="codesandbox"
49+
values={[
50+
{ label: 'Codesandbox', value: 'codesandbox' },
51+
{ label: 'Stackblitz', value: 'stackblitz' },
52+
]}
53+
>
54+
<TabItem value="stackblitz">
55+
<a
56+
target="_blank"
57+
href="https://stackblitz.com/github/Lemoncode/react-image-focal-point/tree/main/examples/basic?embed=1&file=src%2Fapp.tsx"
58+
>
59+
<img
60+
src="https://developer.stackblitz.com/img/open_in_stackblitz.svg"
61+
alt="Edit on StackBlitz"
62+
title="Edit on StackBlitz"
63+
/>
64+
</a>
65+
<iframe
66+
src="https://stackblitz.com/github/Lemoncode/react-image-focal-point/tree/main/examples/basic?embed=1&file=src%2Fapp.tsx"
67+
style={{ width: '100%', height: '500px', border: 0, borderRadius: '4px', overflow: 'hidden' }}
68+
></iframe>
69+
</TabItem>
70+
<TabItem value="codesandbox">
71+
<a
72+
target="_blank"
73+
href="https://codesandbox.io/s/github/Lemoncode/react-image-focal-point/tree/main/examples/basic?file=/src/app.tsx"
74+
>
75+
<img
76+
src="https://codesandbox.io/static/img/play-codesandbox.svg"
77+
alt="Edit on Codesandbox"
78+
title="Edit on Codesandbox"
79+
/>
80+
</a>
81+
<iframe
82+
src="https://codesandbox.io/embed/github/Lemoncode/react-image-focal-point/tree/main/examples/basic?fontsize=14&hidenavigation=1&module=%2Fsrc%2Fapp.tsx&theme=dark&view=editor"
83+
style={{ width: '100%', height: '500px', border: 0, borderRadius: '4px', overflow: 'hidden' }}
84+
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
85+
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
86+
></iframe>
87+
</TabItem>
88+
</Tabs>

0 commit comments

Comments
 (0)