npm package: @prashantgosai11/bisag-sidebar
Description: Bisag-style sidebar for geospatial data visualization
Latest version: 1.1.10
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Bisag Sidebar

A Bisag-style sidebar component for geospatial data visualization. Add datasets, configure layers, filters, base maps, and export data.

## Features

- **Layers Tab**: Add GeoJSON/CSV/Shapefile data, choose visualization types (point, line, polygon, hexbin, heatmap, etc.)
- **Filters Tab**: Create formula, category, pie, histogram, time series, and table widgets
- **Base Map Tab**: Add vector/raster/WMS tiles
- **Export**: Export to CSV, GeoJSON, WKT, KML, JSON

---

## How to use this package in your project

### 1. Install from npm (one command – no separate dependency install)

```bash
npm install @prashantgosai11/bisag-sidebar
```

**You do not need to install Mantine, React, MapLibre GL, or any other dependency separately.** They are listed as direct dependencies and are installed automatically with this package. A postinstall step ensures they are available in all environments (npm, yarn, pnpm).

- Do **not** run `npm install --ignore-scripts` when installing this package (scripts are required for dependency setup).
- If you see missing-module errors after install, run `npm install` again in your project.

### 2. Use in your app

**Option A – All-in-one (map + sidebar + controls)**  
Use `BisagSidebarWithMap` when you want a ready-made map with the sidebar and map controls (zoom, fullscreen, terrain, basemap):

```tsx
import { BisagSidebarWithMap } from '@prashantgosai11/bisag-sidebar';

export default function MyMapPage() {
  return (
    <BisagSidebarWithMap
      mapOptions={{
        style: 'https://demotiles.maplibre.org/style.json',
        center: [72.5, 23.0],
        zoom: 6,
      }}
    />
  );
}
```

**Option B – Your own map container**  
Use `BisagSidebar`, `MapControls`, and `DeckGlOverlayManager` when you create the map yourself:

```tsx
'use client'; // if using Next.js App Router

import { useRef, useEffect } from 'react';
import maplibregl from 'maplibre-gl';
import {
  BisagSidebar,
  MapControls,
  DeckGlOverlayManager,
  useMapStore,
} from '@prashantgosai11/bisag-sidebar';

export default function MyMapPage() {
  const mapContainer = useRef<HTMLDivElement>(null);
  const map = useMapStore((s) => s.map);
  const setMap = useMapStore((s) => s.setMap);

  useEffect(() => {
    if (!mapContainer.current) return;
    const mapInstance = new maplibregl.Map({
      container: mapContainer.current,
      style: 'https://demotiles.maplibre.org/style.json',
      center: [72.5, 23.0],
      zoom: 6,
    });
    mapInstance.on('load', () => setMap(mapInstance));
    return () => {
      mapInstance.remove();
      setMap(null);
    };
  }, [setMap]);

  return (
    <div style={{ position: 'relative', width: '100vw', height: '100vh' }}>
      <div ref={mapContainer} style={{ width: '100%', height: '100%' }} />
      <DeckGlOverlayManager map={map} />
      <MapControls onOpenBaseMap={() => {}} />
      <BisagSidebar />
    </div>
  );
}
```

- **Next.js**: Use a client component and load the map with `dynamic(..., { ssr: false })`. See [NEXTJS_INTEGRATION.md](./NEXTJS_INTEGRATION.md) for details.
- **CSS**: No need to import CSS manually; the package injects its styles when you import the components.

---

## Install & Run (development of this repo)

```bash
cd /home/bisag/Projects/kepler-sidebar
npm install
npm run dev
```

Open http://localhost:5173

## Usage in Your Project (details)

### Quick Start (With Default Map)

The easiest way to use Bisag Sidebar is with the `BisagSidebarWithMap` component, which includes a MapLibre GL map:

```tsx
import { BisagSidebarWithMap } from '@prashantgosai11/bisag-sidebar';

function App() {
  return (
    <BisagSidebarWithMap
      mapOptions={{
        style: 'https://demotiles.maplibre.org/style.json',
        center: [72.5, 23.0],
        zoom: 6,
      }}
    />
  );
}
```

> **Note:** 
> - **Mantine** and **maplibre-gl** are installed automatically with `@prashantgosai11/bisag-sidebar` (a postinstall script ensures dependencies are available). You do not need to install `@mantine/core` separately.
> - **CSS is automatically imported** - no need to manually import CSS files! The styles are included automatically when you import the component.
> - If you see a Mantine error after install, run `npm install` again and do not use `npm install --ignore-scripts`.

### Advanced Usage (Custom Map)

If you want to use your own MapLibre GL map instance:

```tsx
import { useRef, useEffect } from 'react';
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import { BisagSidebar, DeckGlOverlayManager, useMapStore } from '@prashantgosai11/bisag-sidebar';
// CSS is automatically imported - no need to manually import bisag-sidebar.css!

function App() {
  const mapContainer = useRef<HTMLDivElement>(null);
  const map = useMapStore((s) => s.map);
  const setMap = useMapStore((s) => s.setMap);

  useEffect(() => {
    if (!mapContainer.current) return;

    const mapInstance = new maplibregl.Map({
      container: mapContainer.current,
      style: 'https://demotiles.maplibre.org/style.json',
      center: [72.5, 23.0],
      zoom: 6,
    });

    mapInstance.on('load', () => {
      setMap(mapInstance);
    });

    return () => {
      mapInstance.remove();
      setMap(null);
    };
  }, [setMap]);

  return (
    <div style={{ position: 'relative', width: '100vw', height: '100vh' }}>
      <div ref={mapContainer} style={{ width: '100%', height: '100%' }} />
      <DeckGlOverlayManager map={map} />
      <BisagSidebar />
    </div>
  );
}
```

## Dependencies

- React 19
- Mantine UI
- deck.gl (layers, mapbox overlay)
- MapLibre GL
- Zustand (state)
- Turf.js, H3, etc.

## Project Structure

```
src/
├── BisagSidebar/     # Main sidebar component
│   ├── tabs/          # Layers, Filters, BaseMap tabs
│   ├── widgets/       # Formula, Category, Pie, etc.
│   └── AddLayers/      # Layer type selector, Deck.gl layer factories
├── AddLayers/          # Deck.gl layer React components
├── stores/             # Map & widget state (Zustand)
├── utils/              # widget-utils, fileLoaders, export-formats
├── types/
├── hooks/
└── App.tsx
```