@paraboly/map-editor

A reusable, generic React + TypeScript Map Editor library designed to be consumed by other Parabol applications (e.g., Cermoni, Safely, Pintask, Mapalyse).

This package provides a rich set of map-editing capabilities, layer management, and import/export tools, all while remaining agnostic to product-specific domain logic. It exposes a customizable <MapEditor /> component via a flexible API.

Features

• Generic Editor Components: Fully encapsulated map editor with drawing tools, a feature tree, layers, and properties editor.
• Library-First API: Configurable readonly modes, customizable theme, and filtered tools array.
• Leaflet Renderer: High-performance rendering engine built on top of Leaflet and Leaflet Draw.
• Import/Export: Out-of-the-box support for importing/exporting GeoJSON, KML, WKT, SHP (Zip), and GTFS (Zip). Exported GeoJSON files are fully compliant with the Mapbox simplestyle-spec 1.1.0, ensuring 100% style compatibility with external tools like GitHub, GeoJSON.io, and QGIS.
• History Management: Built-in Undo/Redo stack for all map actions.

Installation

The library is designed to be consumed by other projects. Make sure to install the peer dependencies:

npm install @paraboly/map-editor leaflet leaflet-draw react react-dom

Usage

Import the MapEditor component and its styles into your React application:

import { useState } from 'react';
import { MapEditor, EditorFeature } from '@paraboly/map-editor';
import '@paraboly/map-editor/style.css';

export default function MyMapApp() {
  const [features, setFeatures] = useState<EditorFeature[]>([]);

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <MapEditor
        value={features}
        theme="light" // or "dark"
        locale="en" // or "tr"
        tools={["select", "marker", "polyline", "polygon", "circle", "text"]}
        readonly={false} // Set to true to disable drawing/editing
        onChange={(newFeatures) => {
          setFeatures(newFeatures);
        }}
        onSelectionChange={(featureId) => {
          console.log("Selected:", featureId);
        }}
        onSave={(snapshot) => {
          console.log("Save triggered with snapshot:", snapshot);
        }}
      />
    </div>
  );
}

Development & Testing

Building the Library

To compile the library's ESM and CommonJS bundles as well as .d.ts definitions:

npm install
npm run build

Running the Local Example

There is an integrated example/ React application included in the repository to test the library locally without publishing. You can easily test the integration as if an external application is importing the compiled package:

npm run test:integration

This custom test:integration script will automatically compile the library first and then start the example project.

Development Workflow: Because example/ consumes the compiled library (dist/ folder), you must run npm run build in the root folder whenever you make changes to the library's src/ files. You do not need to change anything inside example/ unless the library's props/API change.

Publishing to NPM

To publish a new version of the package to NPM, follow these steps from the root directory:

1. Build the project to ensure all outputs are fresh and error-free:

   npm run build

2. Bump the version (choose patch, minor, or major):

   npm version patch

3. Publish (if publishing to a private registry or with a scope, ensure your .npmrc is configured):

   npm publish --access public

Architecture

• src/index.ts: The main entrypoint exposing <MapEditor /> and core types.
• src/MapEditor.tsx & src/MapEditorContext.tsx: The wrapper component and its context.
• src/core: Reusable generic API for geometries, commands, undo/redo, validation, and import/export.
• src/editor: Zustand store, history tracking, and shortcuts.
• src/features: React UI panels (Toolbar, Feature Tree Panel, Edit Panel, etc.).
• src/map: Map engine adapters (currently Leaflet).