@j3m-quantum/ui 1.7.0 → 1.9.1

package/README.md

@@ -8,6 +8,13 @@ J3M Quantum UI - A React component library with J3M design tokens.
 - **Tailwind CSS v4** (required - not compatible with v3)
 - **tw-animate-css** >= 1.0.0
 
+### Optional Peer Dependencies
+
+| Package | Version | Required For |
+|---------|---------|--------------|
+| `leaflet` | ^1.9.4 | Map components |
+| `react-leaflet` | ^5.0.0 | Map components |
+
 ## Features
 
 - **J3M Design Tokens** - Orange primary, neutral grays, pill-shaped buttons
@@ -272,6 +279,9 @@ Dialog, Drawer, Sheet, Popover, HoverCard
 ### Layout
 ScrollArea, Collapsible, Resizable, Sidebar, SidebarProvider, SidebarInset, Section
 
+### Map
+Map, MapTileLayer, MapMarker, MapPopup, MapTooltip, MapZoomControl
+
 ### Utilities
 ThemeSwitch, ToolbarCanvas, PlayerCanvas
 
@@ -381,6 +391,96 @@ const navItems: NavItem[] = [
 <NavMain items={navItems} />
 ```
 
+## Map Components
+
+Leaflet-based map components for displaying interactive maps. **Requires optional peer dependencies.**
+
+### Installation
+
+```bash
+npm install leaflet react-leaflet
+```
+
+### Setup
+
+Import Leaflet CSS in your app's entry CSS file:
+
+```css
+/* src/index.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@j3m-quantum/ui/styles";
+@import "leaflet/dist/leaflet.css";
+```
+
+### Basic Usage
+
+```tsx
+import { Map, MapTileLayer, MapMarker, MapPopup } from '@j3m-quantum/ui'
+
+function MyMap() {
+  return (
+    <Map center={[57.7089, 11.9746]} zoom={12} className="h-[400px]">
+      <MapTileLayer />
+      <MapMarker position={[57.7089, 11.9746]}>
+        <MapPopup>Hello from Gothenburg!</MapPopup>
+      </MapMarker>
+    </Map>
+  )
+}
+```
+
+### Tile Layer Variants
+
+```tsx
+// Default (OpenStreetMap)
+<MapTileLayer variant="default" />
+
+// Dark mode tiles
+<MapTileLayer variant="dark" />
+
+// Satellite imagery
+<MapTileLayer variant="satellite" />
+```
+
+### Map Components Reference
+
+| Component | Description |
+|-----------|-------------|
+| `Map` | Main map container. Requires explicit height via `className` or `style`. |
+| `MapTileLayer` | Tile layer for map background. Supports `default`, `dark`, `satellite` variants. |
+| `MapMarker` | Marker at a specific position. Can contain Popup and Tooltip children. |
+| `MapPopup` | Popup that appears when a marker is clicked. |
+| `MapTooltip` | Tooltip that appears on marker hover. |
+| `MapZoomControl` | Custom zoom control positioning (MapContainer has built-in controls). |
+
+### Fixing Marker Icons
+
+Bundlers may break Leaflet's default marker icon paths. Fix by configuring icons in your app:
+
+```tsx
+import L from "leaflet"
+
+delete (L.Icon.Default.prototype as any)._getIconUrl
+L.Icon.Default.mergeOptions({
+  iconRetinaUrl: "https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon-2x.png",
+  iconUrl: "https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon.png",
+  shadowUrl: "https://unpkg.com/leaflet@1.9.4/dist/images/marker-shadow.png",
+})
+```
+
+### React StrictMode
+
+When using React StrictMode, use unique keys on Map components to prevent "already initialized" errors:
+
+```tsx
+const [mapKey] = useState(() => `map-${Date.now()}`)
+
+<Map key={mapKey} center={[57.7089, 11.9746]} zoom={12}>
+  ...
+</Map>
+```
+
 ## Customization
 
 Override CSS variables after the import: