mapixa 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maplibre-gl-tools Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# 🗺️ Mapixa
+
+> A feature-rich, extensible suite of drawing, measurement, navigation, and layer visibility tools for **MapLibre GL JS** and **React**. Built with pure CSS, vanilla JavaScript, and Lucide icons.
+
+[![npm version](https://img.shields.io/npm/v/mapixa.svg?style=flat-square)](https://www.npmjs.com/package/mapixa)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+---
+
+## ✨ Features
+
+- 📍 **Full Draw Suite**:
+  - **Markers**: Custom SVG pins (star, circle, square, classic pin), customizable color, size, opacity, and label.
+  - **Polylines**: Live drafting line, double-click or finish button, custom width, color, and real-time distance calculation.
+  - **Polygons**: Interactive vertex handles, live perimeter drafting, and real-time spherical area calculation ($m^2$ and $km^2$).
+  - **Circles**: Center-point & radius drafting, calculated area, and 64-vertex GeoJSON Polygon generation.
+  - **Rectangles**: Two-point bounding box dragging with live area metrics.
+  - **Freehand Pen**: Smooth freehand brush sketching with configurable stroke width and color.
+  - **Intersections**: Segment intersection detector that flags and computes coordinates of line crossings.
+- 📐 **Measurement & Utilities**:
+  - **Distance Ruler**: Segment distances and total distance calculation in kilometers.
+  - **Area Capture**: Drag-to-select map canvas crop and high-resolution PNG export.
+  - **GoTo Coordinates**: Smooth fly-to navigation with coordinate validation (DD/DMS).
+  - **Image Overlays**: Place, drag, scale, rotate, and adjust opacity of custom image overlays on map coordinates.
+- 👁️ **Layer Visibility System**:
+  - Toggle visibility for all markers, lines, polygons, circles, rectangles, freehand sketches, rulers, and overlays.
+  - Programmatic control via `useLayerVisibility()` and controlled `visibility` prop on the root component.
+- ⚡ **"After Draw" Action Lifecycle**:
+  - `onDrawEnd` event fired whenever any drawing completes, providing the complete GeoJSON feature and calculated metrics.
+  - Multiple modes: `'modal'` (styling modal), `'auto-save'` (silent commit), or `'callback'`.
+  - Inject custom action buttons (`extraActions`) into tool dialogs (e.g., _Save to Cloud API_, _Buffer 500m_, _Download GeoJSON_, _Export KML_).
+- 🧭 **Navigation Controls**:
+  - Reset View (Home), Zoom In/Out, Locate User (GPS), Box Zoom (Shift + Drag), Reset North (Compass).
+  - **Live Coordinate Display**: Cursor hover coordinates with click-to-copy to clipboard.
+- 🎨 **Pure CSS & Zero Framework Bloat**:
+  - No Material UI, No Emotion, No Tailwind requirement.
+  - Modern glassmorphic floating UI with buttery-smooth CSS Grid accordion animations.
+  - Powered by **lucide-react** icons.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install mapixa maplibre-gl react-map-gl
+```
+
+_or with yarn:_
+
+```bash
+yarn add mapixa maplibre-gl react-map-gl
+```
+
+_or with pnpm:_
+
+```bash
+pnpm add mapixa maplibre-gl react-map-gl
+```
+
+---
+
+## 🚀 Quick Start
+
+Wrap your application with MapLibre and mount `<Mapixa />` (or `<MapLibreTools />`) directly inside:
+
+```tsx
+import React from "react";
+import "maplibre-gl/dist/maplibre-gl.css";
+import "mapixa/style.css";
+import maplibregl from "maplibre-gl";
+import { Map } from "react-map-gl/maplibre";
+import { Mapixa } from "mapixa";
+
+export function MyMap() {
+  return (
+    <div style={{ width: "100vw", height: "100vh" }}>
+      <Map
+        mapLib={maplibregl}
+        initialViewState={{
+          longitude: 51.389,
+          latitude: 35.6892,
+          zoom: 12,
+        }}
+        mapStyle="https://basemaps.cartocdn.com/gl/positron-gl-style/style.json"
+        style={{ width: "100%", height: "100%" }}
+      >
+        {/* Mount all tools in one line */}
+        <Mapixa
+          afterDrawMode="modal"
+          onDrawEnd={(event) => {
+            console.log("After draw happened:", event.tool, event.feature);
+          }}
+          visibility={{ polyine: true, circle: false }}
+          toolbarGap={12}
+        />
+      </Map>
+    </div>
+  );
+}
+```
+
+---
+
+## ⚡ Handling "After Draw" Actions
+
+You can customize what happens after the user completes a drawing:
+
+### 1. `onDrawEnd` Lifecycle Hook
+
+Receives a `DrawEndEvent` containing the feature, coordinates, and calculated GIS metrics:
+
+```tsx
+<Mapixa
+  onDrawEnd={(event) => {
+    console.log("Tool used:", event.tool); // 'marker' | 'line' | 'polygon' | 'circle' | etc.
+    console.log("GeoJSON Feature:", event.feature);
+    console.log("Calculated metrics:", event.metrics);
+    // event.metrics?.areaSqKm -> area in square kilometers
+    // event.metrics?.distanceKm -> distance in kilometers
+    // event.metrics?.radiusKm -> circle radius
+  }}
+/>
+```
+
+### 2. Custom Action Buttons (`extraActions`)
+
+Inject custom action buttons directly into tool dialogs:
+
+```tsx
+const customActions = [
+  {
+    id: "save-to-db",
+    label: "Save to Backend",
+    variant: "contained",
+    color: "primary",
+    onClick: async ({ tool, feature, metrics, closeModal }) => {
+      await fetch("/api/features", {
+        method: "POST",
+        body: JSON.stringify({ tool, feature, metrics }),
+      });
+      alert("Feature saved to server!");
+      closeModal?.();
+    },
+  },
+  {
+    id: "export-geojson",
+    label: "Download GeoJSON",
+    variant: "outlined",
+    onClick: ({ tool, feature }) => {
+      downloadGeoJSON(feature, `${tool}.geojson`);
+    },
+  },
+];
+
+<Mapixa extraActions={customActions} />;
+```
+
+### 3. `afterDrawMode` Modes
+
+- `'modal'` _(default)_: Opens the tool's dialog allowing the user to configure styles, view measurements, and trigger custom extra actions.
+- `'auto-save'`: Automatically saves the feature to the map and fires `onDrawEnd` immediately without blocking the user.
+
+---
+
+## 👁️ Layer Visibility Control
+
+Every tool has visibility management configured directly via code and props:
+
+### 1. Controlled Visibility Prop
+
+Pass the `visibility` prop directly to `<Mapixa />`. It accepts tool keys and aliases (e.g. `line`, `polyline`, `polyine`, `circle`, `polygon`, `marker`, etc.):
+
+```tsx
+<Mapixa
+  afterDrawMode="modal"
+  extraActions={extraActions}
+  onDrawEnd={handleDrawEnd}
+  visibility={{
+    polyine: true, // polylines visible
+    circle: false, // circles hidden
+    marker: true, // markers visible
+    polygon: true, // polygons visible
+  }}
+  toolbarGap={12} // customizable gap in px between accordion toolbars (default: 12px)
+/>
+```
+
+### 2. Programmatic Control with `useLayerVisibility`
+
+```tsx
+import { useLayerVisibility } from "mapixa";
+
+function MyComponent() {
+  const {
+    visibility,
+    toggleToolVisibility,
+    setToolVisibility,
+    setAllVisibility,
+  } = useLayerVisibility();
+
+  return (
+    <button onClick={() => toggleToolVisibility("polygon")}>
+      Toggle Polygons ({visibility.polygon ? "Visible" : "Hidden"})
+    </button>
+  );
+}
+```
+
+---
+
+## 🧩 Modular Components
+
+If you prefer custom layouts rather than the all-in-one `<Mapixa />`, you can import individual components:
+
+```tsx
+import {
+  MapControlBox,
+  MapDrawTools,
+  ExtraMapTools,
+  LayerVisibilityControl,
+  MapNavigator,
+  CoordinateDisplay,
+} from "mapixa";
+
+<MapControlBox position="top-right">
+  <MapDrawTools />
+  <ExtraMapTools />
+  <LayerVisibilityControl />
+</MapControlBox>;
+
+<MapControlBox position="bottom-left">
+  <CoordinateDisplay />
+</MapControlBox>;
+
+<MapControlBox position="top-left">
+  <MapNavigator />
+</MapControlBox>;
+```
+
+---
+
+## 🛠️ Exported Utilities
+
+- `calculateDistanceKm(p1, p2)`: Haversine distance in km.
+- `calculateLineDistanceKm(coordinates)`: Total line distance in km.
+- `calculatePolygonAreaSqM(coordinates)`: Spherical polygon area in $m^2$.
+- `createGeoJSONCircle(center, radiusKm)`: GeoJSON Polygon circle generator.
+- `downloadGeoJSON(data, filename)`: Triggers browser download of GeoJSON.
+- `copyToClipboard(text)`: Cross-browser clipboard copy.
+- `downloadCanvasArea(canvas, rect, filename)`: Canvas crop export.
+
+---
+
+## 🚢 Publishing to NPM
+
+To publish this package to NPM under the name **mapixa**:
+
+1. Build the distributable bundle:
+   ```bash
+   npm run build:lib
+   ```
+2. Check the bundle contents:
+   ```bash
+   npm pack --dry-run
+   ```
+3. Login and publish:
+   ```bash
+   npm login
+   npm publish --access public
+   ```
+
+---
+
+## 📄 License
+
+MIT © [Open Source](LICENSE)

package/dist/components/DrawTools/DrawCircleControl.d.ts

@@ -0,0 +1,18 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface CircleItem {
+    id: string;
+    name: string;
+    center: [number, number];
+    radiusKm: number;
+    fillColor: string;
+    fillOpacity: number;
+    outlineColor: string;
+    areaSqKm?: number;
+}
+export interface DrawCircleControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const DrawCircleControl: FC<DrawCircleControlProps>;
+export default DrawCircleControl;

package/dist/components/DrawTools/DrawLineControl.d.ts

@@ -0,0 +1,17 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface LineItem {
+    id: string;
+    name: string;
+    lineColor: string;
+    lineWidth: number;
+    opacity: number;
+    coordinates: number[][];
+    distanceKm?: number;
+}
+export interface DrawLineControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const DrawLineControl: FC<DrawLineControlProps>;
+export default DrawLineControl;

package/dist/components/DrawTools/DrawMarkerControl.d.ts

@@ -0,0 +1,19 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface MarkerItem {
+    id: string;
+    name: string;
+    lat: number;
+    lon: number;
+    markerColor: string;
+    iconType: "star" | "circle" | "square" | "pin";
+    iconColor: string;
+    size: number;
+    opacity: number;
+}
+export interface DrawMarkerControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const DrawMarkerControl: FC<DrawMarkerControlProps>;
+export default DrawMarkerControl;

package/dist/components/DrawTools/DrawPolygonControl.d.ts

@@ -0,0 +1,18 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface PolygonItem {
+    id: string;
+    name: string;
+    fillColor: string;
+    fillOpacity: number;
+    outlineColor: string;
+    vertices: number[][];
+    areaSqM?: number;
+    areaSqKm?: number;
+}
+export interface DrawPolygonControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const DrawPolygonControl: FC<DrawPolygonControlProps>;
+export default DrawPolygonControl;

package/dist/components/DrawTools/DrawRectangleControl.d.ts

@@ -0,0 +1,19 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface RectangleItem {
+    id: string;
+    name: string;
+    p1: [number, number];
+    p2: [number, number];
+    fillColor: string;
+    fillOpacity: number;
+    outlineColor: string;
+    areaSqKm?: number;
+}
+export declare const getRectCoordinates: (p1: [number, number], p2: [number, number]) => number[][];
+export interface DrawRectangleControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const DrawRectangleControl: FC<DrawRectangleControlProps>;
+export default DrawRectangleControl;

package/dist/components/DrawTools/FreeDrawControl.d.ts

@@ -0,0 +1,8 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface FreeDrawControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const FreeDrawControl: FC<FreeDrawControlProps>;
+export default FreeDrawControl;

package/dist/components/DrawTools/IntersectionControl.d.ts

@@ -0,0 +1,8 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface IntersectionControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const IntersectionControl: FC<IntersectionControlProps>;
+export default IntersectionControl;

package/dist/components/DrawTools/MapDrawTools.d.ts

@@ -0,0 +1,9 @@
+import { FC } from 'react';
+import { ToolsConfiguration, ExtraActionItem } from '../../types/tools';
+export interface MapDrawToolsProps {
+    id?: string;
+    config?: ToolsConfiguration;
+    extraActions?: ExtraActionItem[];
+}
+export declare const MapDrawTools: FC<MapDrawToolsProps>;
+export default MapDrawTools;

package/dist/components/ExpandableBox.d.ts

@@ -0,0 +1,11 @@
+import { FC, ReactNode } from 'react';
+export interface ExpandableBoxProps {
+    children: ReactNode;
+    accordionText: string;
+    accordionIcon: ReactNode;
+    id?: string;
+    tooltip?: string;
+    footer?: ReactNode;
+}
+export declare const ExpandableBox: FC<ExpandableBoxProps>;
+export default ExpandableBox;

package/dist/components/ExtraActionButtons.d.ts

@@ -0,0 +1,7 @@
+import { ExtraActionItem, ActionContext } from '../types/tools';
+export interface ExtraActionButtonsProps {
+    actions?: ExtraActionItem[];
+    context: ActionContext;
+}
+export declare function ExtraActionButtons({ actions, context, }: ExtraActionButtonsProps): import("react").JSX.Element;
+export default ExtraActionButtons;

package/dist/components/ExtraTools/CaptureAreaControl.d.ts

@@ -0,0 +1,8 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface CaptureAreaControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const CaptureAreaControl: FC<CaptureAreaControlProps>;
+export default CaptureAreaControl;

package/dist/components/ExtraTools/DrawRulerControl.d.ts

@@ -0,0 +1,8 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface DrawRulerControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const DrawRulerControl: FC<DrawRulerControlProps>;
+export default DrawRulerControl;

package/dist/components/ExtraTools/ExtraMapTools.d.ts

@@ -0,0 +1,9 @@
+import { FC } from 'react';
+import { ToolsConfiguration, ExtraActionItem } from '../../types/tools';
+export interface ExtraMapToolsProps {
+    id?: string;
+    config?: ToolsConfiguration;
+    extraActions?: ExtraActionItem[];
+}
+export declare const ExtraMapTools: FC<ExtraMapToolsProps>;
+export default ExtraMapTools;

package/dist/components/ExtraTools/GoToControl.d.ts

@@ -0,0 +1,7 @@
+import { FC } from 'react';
+import { ToolConfig } from '../../types/tools';
+export interface GoToControlProps {
+    config?: ToolConfig;
+}
+export declare const GoToControl: FC<GoToControlProps>;
+export default GoToControl;

package/dist/components/ExtraTools/ImageOverlayControl.d.ts

@@ -0,0 +1,18 @@
+import { FC } from 'react';
+import { ExtraActionItem, ToolConfig } from '../../types/tools';
+export interface OverlayImageItem {
+    id: string;
+    name: string;
+    src: string;
+    lng: number;
+    lat: number;
+    scale: number;
+    rotation: number;
+    opacity: number;
+}
+export interface ImageOverlayControlProps {
+    config?: ToolConfig;
+    extraActions?: ExtraActionItem[];
+}
+export declare const ImageOverlayControl: FC<ImageOverlayControlProps>;
+export default ImageOverlayControl;

package/dist/components/LayerVisibilityControl/LayerVisibilityControl.d.ts

@@ -0,0 +1,6 @@
+export interface LayerVisibilityControlProps {
+    buttonSize?: number;
+    placement?: "left" | "right" | "top" | "bottom";
+}
+export declare function LayerVisibilityControl({ buttonSize, }: LayerVisibilityControlProps): import("react").JSX.Element;
+export default LayerVisibilityControl;

package/dist/components/MapControlBox.d.ts

@@ -0,0 +1,14 @@
+import { ControlPosition } from 'react-map-gl/maplibre';
+import { ReactNode } from 'react';
+export interface MapControlBoxProps {
+    position?: ControlPosition;
+    margin?: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    children?: ReactNode;
+}
+export declare function MapControlBox({ position, margin, children, }: MapControlBoxProps): import('react').ReactPortal;
+export default MapControlBox;

package/dist/components/MapLibreTools.d.ts

@@ -0,0 +1,85 @@
+import { FC, ReactNode } from 'react';
+import { ControlPosition } from 'react-map-gl/maplibre';
+import { ToolsConfiguration, LayerVisibilityState, AfterDrawMode, ExtraActionItem, ToolType } from '../types/tools';
+import { DrawEndEvent, DrawChangeEvent, DrawDeleteEvent } from '../types/events';
+export interface MapLibreToolsProps {
+    children?: ReactNode;
+    /**
+     * Position for the main draw and extra toolbars.
+     * Defaults to 'top-right'
+     */
+    toolbarPosition?: ControlPosition;
+    /**
+     * Position for navigator zoom/home controls.
+     * Defaults to 'top-left'
+     */
+    navigatorPosition?: ControlPosition;
+    /**
+     * Position for live coordinate display.
+     * Defaults to 'bottom-left'
+     */
+    coordinatePosition?: ControlPosition;
+    /**
+     * Position for fullscreen control.
+     * Defaults to 'bottom-right'
+     */
+    viewControlPosition?: ControlPosition;
+    /**
+     * Controlled or initial visibility of tool layers (markers, lines, polygons, etc.)
+     * Example: visibility={{ polyine: true, circle: false }} or visibility={{ line: true, circle: false }}
+     */
+    visibility?: Partial<LayerVisibilityState>;
+    /**
+     * Initial visibility of tool layers (fallback for uncontrolled)
+     */
+    initialVisibility?: Partial<LayerVisibilityState>;
+    /**
+     * Gap between toolbar accordion boxes in pixels.
+     * Defaults to 12.
+     */
+    toolbarGap?: number;
+    /**
+     * Tool configurations (enabled/disabled, custom extraActions per tool)
+     */
+    toolsConfig?: ToolsConfiguration;
+    /**
+     * Behavior after finishing a draw action:
+     * - 'modal': opens configuration/styling modal with extra actions
+     * - 'auto-save': automatically commits the feature and triggers onDrawEnd
+     * - 'callback': triggers onDrawEnd immediately
+     */
+    afterDrawMode?: AfterDrawMode;
+    /**
+     * Global extra actions injected into all tool modals
+     */
+    extraActions?: ExtraActionItem[];
+    /**
+     * Callback fired when any tool finishes drawing a shape, marker, or measurement
+     */
+    onDrawEnd?: (event: DrawEndEvent) => void;
+    /**
+     * Callback fired when a tool starts drawing
+     */
+    onDrawStart?: (tool: ToolType) => void;
+    /**
+     * Callback fired when features change
+     */
+    onDrawChange?: (event: DrawChangeEvent) => void;
+    /**
+     * Callback fired when a feature is deleted
+     */
+    onDrawDelete?: (event: DrawDeleteEvent) => void;
+    /**
+     * Callback fired when layer visibility toggles
+     */
+    onVisibilityChange?: (tool: ToolType, visible: boolean, allState: LayerVisibilityState) => void;
+    showDrawTools?: boolean;
+    showExtraTools?: boolean;
+    showNavigator?: boolean;
+    showCoordinates?: boolean;
+    showFullscreen?: boolean;
+    enforceFlatView?: boolean;
+    autoResize?: boolean;
+}
+export declare const MapLibreTools: FC<MapLibreToolsProps>;
+export default MapLibreTools;

package/dist/components/NavigationTools/CoordinateDisplay.d.ts

@@ -0,0 +1,7 @@
+import { FC } from 'react';
+export interface CoordinateDisplayProps {
+    precision?: number;
+    showCopyButton?: boolean;
+}
+export declare const CoordinateDisplay: FC<CoordinateDisplayProps>;
+export default CoordinateDisplay;

package/dist/components/NavigationTools/MapFlatViewEnforcer.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Enforces flat 2D Mercator view on the MapLibre map instance (no pitch/bearing tilt)
+ */
+export declare function MapFlatViewEnforcer(): any;
+export default MapFlatViewEnforcer;

package/dist/components/NavigationTools/MapNavigator.d.ts

@@ -0,0 +1,7 @@
+import { FC } from 'react';
+export interface MapNavigatorProps {
+    homeCenter?: [number, number];
+    homeZoom?: number;
+}
+export declare const MapNavigator: FC<MapNavigatorProps>;
+export default MapNavigator;

package/dist/components/NavigationTools/MapResizeHandler.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Automatically debounces resize calls to MapLibre when browser/container size changes
+ */
+export declare function MapResizeHandler(): any;
+export default MapResizeHandler;

package/dist/components/NavigationTools/MapViewControl.d.ts

@@ -0,0 +1,3 @@
+import { FC } from 'react';
+export declare const MapViewControl: FC;
+export default MapViewControl;