# @ixo/surveys

A comprehensive survey library with map integration and custom widgets for impact measurement.

## Features

- **Map Grid Selector Widget**: Interactive map-based survey component with grid cell selection
- **UNL (Universal Natural Location) Integration**: Precise location encoding and management
- **SurveyJS Integration**: Seamless integration with SurveyJS Creator and React components
- **TypeScript Support**: Full TypeScript support with type definitions
- **Responsive Design**: Mobile-friendly components

## Installation

```bash
npm install @ixo/surveys
# or
yarn add @ixo/surveys
# or
pnpm add @ixo/surveys
```

## Peer Dependencies

This package requires React as a peer dependency:

```bash
npm install react react-dom
```

## Usage

### Basic Import

```typescript
import { ITheme, Model, SurveyModel, SurveyCreator, SurveyCreatorComponent, Survey } from "@ixo/surveys";
```

### Map Grid Selector Widget

The Map Grid Selector widget allows users to select precise geographic locations using a grid-based system:

```typescript
import { registerMapGridSelectorCreator } from "@ixo/surveys";

// Register the widget with SurveyJS Creator
registerMapGridSelectorCreator();
```

#### Widget Configuration

The Map Grid Selector supports the following properties:

- `gridPrecision`: Grid precision level (1-20, default: 7)
- `center`: Map center coordinates [longitude, latitude]
- `initialZoom`: Initial zoom level (default: 12)
- `maxZoom`: Maximum zoom level (default: 20)
- `focusOnUser`: Focus on user location (default: true)
- `allowMultiple`: Allow multiple cell selections (default: false)
- `basemapToggle`: Show basemap toggle (default: true)

#### Data Capture Options

Control which location data fields are captured:

- Place information (identifier, name, distance)
- Administrative boundaries (country, state, county, city)
- Address components (postal code, house number, road name)

### Custom Components

#### UNLMap Component

```typescript
import { UNLMap } from '@ixo/surveys';

function MyMapComponent() {
	const handleFeatureClick = featureCollection => {
		console.log('Selected feature:', featureCollection);
	};

	return <UNLMap zoom={12} mapId="my-map" getFeatureCollectionOnClick={handleFeatureClick} />;
}
```

### SurveyJS Integration

```typescript
import { Survey, SurveyCreator } from '@ixo/surveys';

// Use in Survey runtime
function MySurvey() {
	const surveyJson = {
		elements: [
			{
				type: 'map-grid-selector',
				name: 'location',
				title: 'Select your location',
				gridPrecision: 7,
				allowMultiple: false,
			},
		],
	};

	return <Survey model={new SurveyModel(surveyJson)} />;
}

// Use in Survey Creator
function MySurveyCreator() {
	return <SurveyCreator />;
}
```

## Development

### Building the Package

```bash
# Build TypeScript
pnpm run build

# Build and create package
pnpm run build:local

# Clean build artifacts
pnpm run clean
```

### Package Structure

```
dist/
├── components/          # React components
├── icons/              # Icon components
├── services/           # Utility services
├── widgets/            # SurveyJS widgets
├── config.js           # Configuration
├── index.js            # Main entry point
└── *.d.ts             # TypeScript definitions
```

## API Reference

### Core Exports

- `ITheme`, `Model`, `SurveyModel`: SurveyJS core components
- `SurveyCreator`, `SurveyCreatorComponent`: SurveyJS Creator components
- `Survey`: SurveyJS React UI component

### Custom Components

- `UNLMap`: Interactive map component with UNL integration
- `MapIcon`: Map icon component

### Widgets

- `map-grid-selector`: Grid-based location selector widget

### Services

- UNL encoding/decoding utilities
- Map styling and configuration

## Support

For issues and questions, please refer to the IXO documentation or create an issue in the repository.