npm package: @majlxrd/inpost-geowidget-next
Description: A React/Next.js component for the InPost GeoWidget.
Author: majlxrd
Latest version: 1.0.1

# React InPost GeoWidget

[![NPM Version](https://img.shields.io/npm/v/@majlxrd/inpost-geowidget-next.svg)](https://www.npmjs.com/package/@majlxrd/inpost-geowidget-next)
[![License](https://img.shields.io/npm/l/@majlxrd/inpost-geowidget-next.svg)](https://opensource.org/licenses/MIT)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@majlxrd/inpost-geowidget-next.svg)](https://bundlephobia.com/result?p=@majlxrd/inpost-geowidget-next)

A lightweight and simple React component for integrating the official InPost GeoWidget v5 into your React and Next.js
applications.

This component handles the dynamic loading of the required InPost scripts and stylesheets, providing a clean and
straightforward way to display the parcel locker map.

## Features

- **Easy Integration**: Drop the component into your app, provide a token, and you're ready to go.
- **Dynamic Script Loading**: Automatically loads the InPost GeoWidget JavaScript and CSS files without needing to add
  them to your `layout.js/ts`.
- **TypeScript Support**: Written entirely in TypeScript, providing full type safety for all props.
- **Event Callbacks**: Easily handle events like point selection (`onPointSelect`) and API readiness (`onApiReady`).
- **Next.js 13+ Ready**: Fully compatible with the Next.js App Router (requires the `"use client";` directive).
- **Customizable**: Supports all standard GeoWidget options like `language`, `config`, and `sandbox` mode.

## Installation

You can install the package using npm or yarn.

**Using npm:**

```bash
npm install @majlxrd/inpost-geowidget-next
```

**Using yarn:**

```bash
yarn add @majlxrd/inpost-geowidget-next
```

## Usage

Here's a basic example of how to use the `InpostGeowidget` component in a Next.js 13+ application.

```tsx
// app/page.tsx
"use client"; // This is required for components with hooks and event listeners in Next.js App Router.

import React, {useState} from 'react';
import InpostGeowidget, {InpostGeowidgetProps} from '@majlxrd/inpost-geowidget-next';

export default function HomePage() {
    const [selectedPoint, setSelectedPoint] = useState<any>(null);

    const handlePointSelect: InpostGeowidgetProps['onPointSelect'] = (point) => {
        console.log("Parcel locker selected:", point);
        setSelectedPoint(point);
    };

    const handleApiReady: InpostGeowidgetProps['onApiReady'] = (api) => {
        console.log("GeoWidget API is ready:", api);
        // You can now use the API, for example: api.openMap();
    };

    return (
        <main style={{padding: '2rem', textAlign: 'center'}}>
            <h1>Select an InPost Parcel Locker</h1>

            {/* The container MUST have a defined width and height for the widget to be visible. */}
            <div style={{width: '800px', height: '500px', margin: '2rem auto', border: '1px solid #ccc'}}>
                <InpostGeowidget
                    token="YOUR_INPOST_API_TOKEN"
                    sandbox={true} // Use true for testing, false for production
                    onPointSelect={handlePointSelect}
                    onApiReady={handleApiReady}
                    language="en"
                />
            </div>

            {selectedPoint && (
                <div style={{marginTop: '1rem', padding: '1rem', backgroundColor: '#f0f0f0'}}>
                    <h3>Selected Point Details:</h3>
                    <p><strong>Name:</strong> {selectedPoint.name}</p>
                    <p>
                        <strong>Address:</strong> {`${selectedPoint.address_details.street}, ${selectedPoint.address_details.city}`}
                    </p>
                </div>
            )}
        </main>
    );
}
```

## Props

The `InpostGeowidget` component accepts the following props:

| Prop Name       | Type                                             | Default         | Description                                                                                       |
|-----------------|--------------------------------------------------|-----------------|---------------------------------------------------------------------------------------------------|
| `token`         | `string`                                         | (none)          | Required. The unique authentication token to initialize the widget.                               |
| `identifier`    | `string`                                         | `GeoWidgetHost` | A unique ID for the widget instance, useful if you have multiple widgets on the same page.        |
| `sandbox`       | `boolean`                                        | `false`         | If true, the widget will use the sandbox (test) environment.                                      |
| `language`      | `'pl', 'en', 'cz', 'sk', 'hu', 'it', 'es', 'fr'` | `'pl'`          | 	The display language for the widget.                                                             |
| `config`        | `string`                                         | `parcelCollect` | The widget's configuration mode, which determines its behavior (e.g., parcelCollect, parcelSend). |
| `onPointSelect` | `(point: any) => void`                           | `undefined`     | Callback function invoked when a user selects a point on the map.                                 |
| `onApiReady`    | `(api: any) => void`                             | `undefined`     | Callback function invoked when the widget's JavaScript API is ready for programmatic control.     |


## Handling Events

`onPointSelect`
This callback receives the selected point object as its only argument. You can use this to store the user's choice in your application's state.

```jsx
const handleSelection = (point) => {
  console.log('User selected:', point.name, point.address_details);
  // Update your form state here
};

<InpostGeowidget token="..." onPointSelect={handleSelection} />
```

`onApiReady`
This callback receives the widget's API object, which you can use to control the widget programmatically.

```jsx
const [widgetApi, setWidgetApi] = useState(null);

// You can now call methods like widgetApi.openMap() from a button click
<button onClick={() => widgetApi?.openMap()}>Open Map</button>

<InpostGeowidget token="..." onApiReady={setWidgetApi} />
```


## Contributing
Contributions are welcome! Please feel free to open an issue or submit a pull request if you have any improvements or bug fixes.

## License
This project is licensed under the MIT License.