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)

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):

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:

'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 for details.
• CSS: No need to import CSS manually; the package injects its styles when you import the components.

Theme / accent color (--bisag-accent)

All sidebar buttons and icons use the accent color via the CSS variable --bisag-accent (default: #f1871c). You can provide or override it in two ways:

1. Using BisagSidebarWithMap – pass accentColor:

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

<BisagSidebarWithMap accentColor="#2563eb" mapOptions={{ ... }} />

2. Using CSS – set the variable on a parent (e.g. root or wrapper):

import { DEFAULT_BISAG_ACCENT, BISAG_ACCENT_CSS_VAR } from '@prashantgosai11/bisag-sidebar';

// In your wrapper or global CSS:
<div style={{ [BISAG_ACCENT_CSS_VAR]: '#059669' }}>
  <BisagSidebar />
</div>

// Or in CSS:
.bisag-sidebar-root { --bisag-accent: #059669; }

Exports: DEFAULT_BISAG_ACCENT ('#f1871c') and BISAG_ACCENT_CSS_VAR ('--bisag-accent') are exported so you can reference the default or the variable name in code.

Install & Run (development of this repo)

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:

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:

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