@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

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

Peer Dependencies

This package requires React as a peer dependency:

npm install react react-dom

Usage

Basic Import

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:

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

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

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

# 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.