@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

Stylesheets (required)

This package does not import the SurveyJS stylesheets for you (keeping CSS out of the JS lets bundlers like Next.js consume it directly, without listing it in transpilePackages). Import the styles you need once in your app entry:

import "survey-core/survey-core.css";
// Only if you use the SurveyCreator UI:
import "survey-creator-core/survey-creator-core.css";

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.