map-boundary-editor 0.1.0 → 0.3.0

package/README.md

@@ -1,11 +1,15 @@
 # map-boundary-editor
 
-**map-boundary-editor** is a generic, embeddable, map-based boundary editor
-implemented as a Web Component.
+[![npm](https://img.shields.io/npm/v/map-boundary-editor)](https://www.npmjs.com/package/map-boundary-editor)
+[![license](https://img.shields.io/npm/l/map-boundary-editor)](LICENSE)
+[![downloads](https://img.shields.io/npm/dm/map-boundary-editor)](https://www.npmjs.com/package/map-boundary-editor)
 
-It allows users to visually draw and edit a geographic boundary
-and outputs a standard **GeoJSON** representation that can be reused
-across different map engines and backend systems.
+**map-boundary-editor** is a lightweight, embeddable map-based boundary editor
+designed for defining and validating geographic service boundaries.
+
+It is optimized for use cases where a **user-defined area (polygon)** must be
+evaluated against a **fixed administrative or reference boundary** — such as
+service eligibility, coverage restriction, or zoning rules.
 
 ---
 
@@ -18,6 +22,9 @@ Many applications need users to define geographic areas:
 - eligibility rules
 - geofencing configuration
 
+A common requirement in these use cases is a clear separation between
+**editable user input** and **non-editable reference boundaries**.
+
 Most teams end up rebuilding the same map drawing logic again and again,
 tightly coupled to a specific map provider.
 
@@ -29,15 +36,31 @@ tightly coupled to a specific map provider.
 
 ---
 
-## Features (v0.1)
+## Key Concepts
+
+### Editable Polygon
+
+A polygon created or modified by the user to represent an area of interest
+(e.g. delivery zone, service coverage).
+
+### Reference Boundary
 
-- Draw, edit, and delete a polygon boundary
-- Leaflet-based (no API key required)
-- Outputs standard GeoJSON (RFC 7946)
-- Framework-agnostic (Web Component)
-- Easy to embed in any web application
+A fixed, non-editable boundary used as a reference for validation or restriction.
+Typical examples include cities, provinces, or regulatory zones.
 
-> Note: v0.1 supports a single boundary only.
+### Readonly Mode
+
+A mode where editing controls are disabled, allowing the map to be used purely
+for visualization, review, or approval workflows.
+
+---
+
+## Features
+
+- Draw, edit, and delete **editable polygon** boundaries
+- Support for fixed, non-editable **reference boundaries**
+- Read-only mode for review or visualization use cases
+- Supports multiple editable boundaries (GeoJSON `FeatureCollection`)
 
 ---
 
@@ -51,73 +74,165 @@ npm install map-boundary-editor
 
 ---
 
-### Via script tag
-
-```html
-<script src="map-boundary-editor.min.js"></script>
-```
-
----
+## Basic Usage (Recommended)
 
-## Basic Usage
+The most common usage pattern is defining an editable area **within** a fixed reference boundary.
 
 ```html
-<map-boundary-editor style="width: 800px; height: 500px;"></map-boundary-editor>
-
-<script>
-  const editor = document.querySelector("map-boundary-editor");
+<map-boundary-editor
+  id="editor"
+  style="width: 800px; height: 500px;"
+></map-boundary-editor>
+
+<script type="module">
+  import "map-boundary-editor";
+
+  const editor = document.getElementById("editor");
+
+  // Set a fixed reference boundary (e.g. administrative area)
+  editor.setBoundary({
+    type: "FeatureCollection",
+    features: [
+      {
+        type: "Feature",
+        geometry: {
+          type: "Polygon",
+          coordinates: [
+            [
+              [106.69, -6.1],
+              [107.03, -6.1],
+              [107.03, -6.38],
+              [106.69, -6.38],
+              [106.69, -6.1],
+            ],
+          ],
+        },
+        properties: {},
+      },
+    ],
+  });
 
+  // Listen for user-defined polygon changes
   editor.addEventListener("change", (e) => {
-    console.log("GeoJSON:", e.detail.geojson);
+    console.log("Editable GeoJSON:", e.detail.geojson);
   });
 </script>
 ```
 
+> All public APIs (`setView`, `setGeoJSON`, `clear`, etc.) are safe to call
+> immediately after the element is created.
+> No `setTimeout` or `customElements.whenDefined` is required.
+
 ---
 
-## Loading an Existing Boundary
+### Loading an Existing Editable Boundary
 
 ```js
 editor.setGeoJSON({
-  type: "Feature",
-  geometry: {
-    type: "Polygon",
-    coordinates: [
-      [
-        [106.8166, -6.2],
-        [106.82, -6.21],
-        [106.83, -6.205],
-        [106.8166, -6.2],
-      ],
-    ],
-  },
-  properties: {},
+  type: "FeatureCollection",
+  features: [
+    {
+      type: "Feature",
+      geometry: {
+        type: "Polygon",
+        coordinates: [
+          [
+            [106.8166, -6.2],
+            [106.82, -6.21],
+            [106.83, -6.205],
+            [106.8166, -6.2],
+          ],
+        ],
+      },
+      properties: {},
+    },
+  ],
 });
 ```
 
+Even when loading a single boundary, the data must be wrapped in a `FeatureCollection` for consistency.
+
+---
+
+### View Control
+
+```js
+editor.setView(lat, lng, zoom);
+```
+
+If editable boundaries are later loaded using `setGeoJSON`, the map will automatically fit to the boundary.
+
 ---
 
-## Public API (v0.1)
+### Optional: Geolocation Helper
+
+An optional geolocation helper is available to center the map on the user's current location.
 
-`getGeoJSON(): GeoJSON`
+This feature only affects the initial view and does not modify boundaries or output GeoJSON.
 
-Returns the current boundary as GeoJSON.
+```html
+<map-boundary-editor use-geolocation></map-boundary-editor>
+```
+
+---
 
-`setGeoJSON(geojson: GeoJSON): void`
+## Public API (v0.3)
 
-Loads a boundary from GeoJSON and renders it on the map.
+### Editable Polygon
+
+`setGeoJSON(geojson: FeatureCollection): void`
+
+Loads editable polygon boundaries from GeoJSON.
+
+`getGeoJSON(): FeatureCollection`
+
+Returns the current editable polygon boundaries.
 
 `clear(): void`
 
-Removes the current boundary.
+Removes all editable polygon boundaries.
+
+---
+
+### Reference Boundary
+
+`setBoundary(geojson: FeatureCollection): void`
+
+Sets a fixed, non-editable reference boundary.
+
+`getBoundary(): FeatureCollection | null`
+
+Returns the current reference boundary.
+
+`clearBoundary(): void`
+
+Removes the reference boundary from the map.
+
+---
+
+### Mode Control
+
+`setReadonly(value: boolean): void`
+
+Enables or disables editing controls.
+
+`isReadonly(): boolean`
+
+Returns the current readonly state.
 
 ---
 
+### View Control
+
+`setView(lat: number, lng: number, zoom?: number): void`
+
+Moves the map to the specified location.
+
 ## Events
 
-`change`
+### change
 
-Fired whenever the boundary is created, edited, or deleted.
+Fired whenever the editable polygon is created, edited, or deleted.
 
 ```js
 editor.addEventListener("change", (e) => {
@@ -131,8 +246,7 @@ editor.addEventListener("change", (e) => {
 
 The editor uses GeoJSON as its data contract.
 
-GeoJSON is treated as the single source of truth and is intentionally decoupled
-from any specific map engine.
+GeoJSON is treated as the single source of truth and is intentionally decoupled from any specific map engine.
 
 The output is compatible with:
 
@@ -142,11 +256,32 @@ The output is compatible with:
 
 ---
 
+## Demo
+
+A demo is included in the repository to showcase:
+
+- Editable polygons vs administrative reference boundaries
+- Visual hierarchy between reference and user-defined areas
+- Readonly vs editable interaction modes
+
+The demo also serves as a reference implementation for integrating the component
+into real-world applications.
+
+---
+
 ## Roadmap
 
-- v0.2: multiple boundaries (FeatureCollection)
-- v0.3: read-only mode
+- v0.3: reference boundary support, read-only mode, improved demo UX
 - v0.4: additional map engine adapters (MapLibre, Google Maps)
 - v1.0: stable API
 
 ---
+
+## Non-Goals
+
+This project is intentionally not:
+
+- A full GIS editor
+- A GeoJSON validation library
+- A replacement for tools like geojson.io
+- A general-purpose map rendering framework