@e-llm-studio/federated-map-view

Reusable, backend-agnostic Google Map component — the host — with map features organized as self-contained modules under src/features/. Extracted from the app's src/lib/federated-map-view; if the in-app map view changes before the migration fully lands, re-sync src/ here.

Run the demo locally

npm install
npm start          # CRA demo harness (src/App.tsx) at http://localhost:3000

Put a Google Maps JavaScript API key in .env (REACT_APP_GOOGLE_MAPS_API_KEY=...) or paste one into the prompt shown on first load. The demo wires up markers, info windows, filters, a seed boundary, and an event log so every callback can be exercised (draw, close loop, save, move/reshape, undo/redo, delete).

npm run build produces the publishable dist/ (ESM + CJS + types) via rollup; src/App.tsx / src/index.tsx are demo-only and excluded from it.

Structure

federated-map-view/
├── package.json / tsconfig / craco / rollup   # package + demo + build config
├── public/                   # CRA demo shell
└── src/
    ├── index.ts              # public entry point (library)
    ├── index.tsx, App.tsx    # demo harness (not published)
    ├── FederatedMapView.tsx  # the host: owns the GoogleMap + map-only UI state
    ├── types.ts              # public API types (re-exports feature types)
    ├── constants.ts          # default center/zoom, map styles, layer options
    ├── styles.css            # host styles (container, search, layers, filters, …)
    ├── components/           # host UI: SearchBox, LayerControl, FilterPanel,
    │                         # MarkersLayer, PolygonsLayer
    ├── utils/
    │   └── googleMaps.ts     # marker/overlay/street-view helpers
    └── features/             # self-contained feature modules
        └── polygon-drawing/  # custom-boundary drawing (see its README)

Adding a future feature: create features/<feature-name>/ with its own index.ts, types.ts, and styles.css, keep all its imports relative, wire it into FederatedMapView.tsx, and re-export its public types from the top-level types.ts / index.ts — exactly the pattern polygon-drawing follows.

Peer dependencies

The consuming app must install and provide these:

• react / react-dom
• @react-google-maps/api
• lucide-react (polygon-drawing glyphs)
• primereact + primeicons (FilterPanel + Manage Custom Boundaries controls)

PrimeReact setup (required)

FilterPanel and the Manage Custom Boundaries panel are built on PrimeReact, so the host app must set PrimeReact up once at its root — otherwise its overlay components (the boundary row menu, etc.) throw Cannot read properties of undefined (reading 'hideOverlaysOnDocumentScrolling') on scroll:

import { PrimeReactProvider } from "primereact/api";
import "primereact/resources/themes/lara-light-blue/theme.css"; // any theme
import "primereact/resources/primereact.min.css";
import "primeicons/primeicons.css";

<PrimeReactProvider>
  <App /> {/* renders <FederatedMapView /> somewhere inside */}
</PrimeReactProvider>

Design rules

• No data fetching, store access, or business logic. The consumer provides data via props and reacts via actions / feature callbacks; the host app owns persistence and state.
• Generic payloads: data-carrying shapes are generic over T so no app-specific type leaks into the library.
• No bundled assets: icons are inline SVG or icon-font packages; image icons come in via *IconUrl props.
• CSS is plain, fmv--prefixed, and imported as side effects (styles.css per module) — the library build must handle CSS imports.

Testing the library copy

1. The in-app twin at src/lib/federated-map-view is the living reference — the code here is identical apart from the features/ reorganization, so behavior can be compared 1:1 (draw, close loop, save, move/reshape, undo/redo, delete).
2. After copying into the library repo, exercise it through the library's demo/consumer with the same flows.
3. For unit tests, @googlemaps/jest-mocks (already used by this app's map spec) can drive useBoundaryDrawing against a mocked google.maps.