Skip to content

Commit 68349d1

Browse files
nasdannasdan
authored
Merge pull request #10 from Lemoncode/feature/#7-documentations
Feature/#7 documentations
2 parents fff4c35 + bb12080 commit 68349d1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+28132
-9165
lines changed

‎.github/workflows/docs.yml

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Publish Docs
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
branches:
7+
- main
8+
paths:
9+
- docs/**
10+
- website/**
11+
- .github/workflows/docs.yml
12+
13+
jobs:
14+
publish-docs:
15+
runs-on: ubuntu-latest
16+
environment:
17+
name: Docs
18+
url: https://lemoncode.github.io/react-image-focal-point
19+
steps:
20+
- name: Checkout Repository
21+
uses: actions/checkout@v3
22+
23+
- name: Add NPM registry
24+
uses: actions/setup-node@v3
25+
with:
26+
node-version: 18.x
27+
28+
- name: Use SSH key
29+
run: |
30+
mkdir -p ~/.ssh/
31+
echo "${{secrets.SSH_PRIVATE_KEY}}" > ~/.ssh/id_rsa
32+
sudo chmod 600 ~/.ssh/id_rsa
33+
34+
- name: Config git
35+
run: |
36+
git config --global user.email "docs@lemoncode.net"
37+
git config --global user.name "Docs bot"
38+
39+
- name: Install
40+
run: npm ci
41+
42+
- name: Publish Docs
43+
run: |
44+
cd ./website
45+
npm run build
46+
npm run deploy

‎.github/workflows/publish-packages.yml renamed to ‎.github/workflows/packages.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ on:
44
push:
55
branches:
66
- main
7+
paths-ignore:
8+
- docs/**
9+
- website/**""
10+
- .github/workflows/docs.yml
711

812
jobs:
913
publish-package:

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

0 commit comments

Comments
 (0)