pixel-perfect-overlay/README.md

A customizable pixel-perfect overlay with adjustable offset and opacity

# Pixel Perfect Overlay

`pixel-perfect-overlay` is a script for adding an image overlay with adjustable offset, opacity, and image upload functionality via URL or drag-and-drop. It's easy to integrate into projects and is perfect for development with visual testing capabilities.

## Installation

To install the package in your project, run the following command:

```bash
npm install pixel-perfect-overlay --save-dev
```

Or using `yarn`:

```bash
yarn add pixel-perfect-overlay --dev
```

## Usage

After installation, simply import the script into your project. Add the following import to your main JavaScript file:

```js
import 'pixel-perfect-overlay';
```

This will load the script, and it will start working automatically without the need for additional initialization. The package will create a control panel for configuring the image overlay and manage all functionality (offset, opacity, image upload).

## Main Features

1. **Image Upload**: 
   - You can upload an image via URL or using drag-and-drop (file dragging).
   - **URL Image**: Change the image URL using the input field in the control panel.
   - **Drag-and-Drop**: Just drag and drop an image file into the browser window, and it will automatically load as the overlay.

2. **Adjust Offset**: 
   - The overlay can be moved using the arrow keys on the keyboard:
     - **Arrow Left** and **Arrow Right** adjust the position along the X-axis.
     - **Arrow Up** and **Arrow Down** adjust the position along the Y-axis.
     - Use **Shift + Arrow** to move the overlay by 10 pixels instead of 1 pixel.

3. **Opacity Control**: 
   - The overlay's opacity can be adjusted via a slider in the control panel.

4. **Control Panel**:
   - The control panel appears by clicking the settings button and allows you to configure:
     - Image URL.
     - Overlay opacity.
     - Overlay offset (X and Y axes).

5. **Saving Settings**: 
   - All changes are saved to `localStorage`. This allows settings such as offset, opacity, and image to persist across page reloads.

6. **Show/Hide Overlay**:
   - The overlay can be toggled on and off using a button in the control panel.

## Available Methods

- **No Initialization Required**: The package starts working automatically as soon as it is imported, so you don’t need to initialize anything or pass any initial values. All settings can be changed through the control panel interface.

## Notes

- This package is intended for use in development builds. It is useful for visual testing and working with image overlays.
- To upload an image using drag-and-drop, simply drag the image file into the browser window. The package will automatically detect the image and load it as the overlay.
- The package uses `localStorage` to save the state, so settings such as image position and opacity will be retained between sessions.

## License

This project is licensed under the MIT License.