Filament Map Picker Laravel Package

Product Decisions This Supports

Buy vs. build for geo-capture UI. This package answers a recurring "do we build a map field or buy one" question. The scope is narrow — a Filament form field plus an infolist entry that returns lat/lng (and optional GeoJSON) — so the comparison is honest: buying saves roughly the 3–10 engineering days it takes to wire Leaflet into Livewire, sync marker state into form state, serialize geometry, and handle hydration on edit screens. That is the entire value proposition, and it is a real one for an internal-tools team.

Feature scoping — what ships in v1 of a geo feature. The package lets you ship "pick a point" without committing to a geospatial platform. Concretely, it de-risks and unblocks:

• Store/dealer/branch locator — capture coordinates on a Location resource; render the same point read-only via MapEntry on the view page.
• Service-area and delivery-zone definition — GeoMan's polygon, circle, rectangle, and cut tools let ops define coverage areas as GeoJSON, stored alongside the point. This is the highest-leverage capability here; it turns a "coordinate field" into a lightweight zone editor.
• Radius-based pricing/tiers — rangeSelectField binds a second form field (in meters) to a live circle on the map. That gives you a visual, self-explanatory configuration screen for distance bands instead of a bare numeric input users mis-set.
• Territory or region restriction — boundaries() (plus the setBoundsToBritishIsles convenience) constrains selection to a bounding box, which is a product-level guardrail: bad coordinates become hard to enter rather than something you validate after the fact.
• Geo-tagged records generally — properties, events, assets, field-survey entries, incident reports.

Roadmap decisions this informs. Because it is MIT and a single composer require, it is a cheap spike/validation tool: ship a geo field to internal users, measure whether coordinate capture actually gets used, then decide whether to invest in geocoding, PostGIS spatial queries, or a routing provider. It lets you defer the expensive platform decision without blocking the feature.

Explicit scope boundaries you must decide separately. The package is a picker, not a geo platform. It does not do address search or reverse geocoding — users pan and zoom to find a location, which is a genuine UX gap for consumer-facing flows and needs a separate geocoding integration. It does not do spatial queries, distance calculations server-side, or validation. And tiling is a real cost/ops decision: the default tile URL points at public OpenStreetMap infrastructure, whose tile usage policy is not intended for production traffic — you need your own tile host or a commercial tile provider URL. Budget that as a line item, not an afterthought.

Privacy decision it forces. liveLocation(true, true, 5000) periodically posts the user's device location to the server. Even for internal users, that needs a consent/labelling decision and a data-retention stance, and it requires HTTPS. Decide whether it is on by default or opt-in per form.

When to Consider This Package

Adopt when most of these hold:

• The application is Filament v3 and the need is an admin/back-office form, not a customer-facing map experience.
• You need point capture plus optional geometry drawing, not geocoding, routing, or spatial analysis.
• OpenStreetMap tiles are acceptable — the package supports OSM only; other providers are reachable via tilesUrl but are untested territory.
• Your team is small enough that a few days of front-end/Livewire plumbing is the real cost, and there is no one to own a bespoke map component.
• The surface is one to a handful of fields (locations, zones, territories), so a single-purpose field beats adopting a mapping SDK.
• You are comfortable with vendor risk proportional to the stakes: MIT licensed, small star count and zero dependents means low adoption signal — fine for an internal tool, thin for a revenue-critical surface.

Look elsewhere (or build) when:

• You need Filament v4 or v2 support, or a guaranteed upgrade path — the README targets v3, and pinning ^1.8 is your only compatibility contract.
• Address search / autocomplete / reverse geocoding is a requirement. This package does not geocode; you would pair it with a geocoder or pick a full mapping solution.
• Google Maps or Mapbox is mandated by brand, licensing, or existing contracts.
• You need spatial querying at scale (nearest-store lookups, polygon containment in SQL). Storing GeoJSON here is necessary but not sufficient — plan PostGIS or an equivalent separately.
• The feature is customer-facing and high-traffic: a small package with no formal support, no stated test suite, and public-OSM tile defaults is a poor fit for a public surface where a broken map is a visible outage.
• You require enterprise support, SLAs, or active maintainer responsiveness as a procurement condition.

How to Pitch It (Stakeholders)

For executives (the 30-second version): This is a free, MIT-licensed map field for our admin panel that lets staff drop a pin or draw a service area and saves the coordinates to the record. It removes several days of custom front-end work per geo feature and lets us test whether location data is actually valuable before we commit budget to a mapping or GIS platform. Total cost: one dependency, plus a decision on tile hosting if we put real traffic through it. Risk is contained — it is an admin-panel component, it is removable in an afternoon, and it locks us into no vendor.

For engineering (the honest version): It is a Filament v3 custom field wrapping Leaflet with OpenStreetMap tiles, plus a matching MapEntry for infolists. Form state arrives as an array (lat, lng, optional geojson); you map it into real columns via afterStateUpdated and rehydrate on edit via afterStateHydrated. GeoMan gives us polygon/circle/rectangle drawing with edit, cut, rotate, and drag modes. Three things we own, not the package: (1) validation — nothing stops a null or out-of-range coordinate, so add rules on the lat/lng columns; (2) tiles — swap tilesUrl off the public OSM endpoint before production and confirm the provider's terms; (3) the refreshMap event pattern if any other field or action needs to move the pin.

The ask: Approve a timeboxed pilot on one internal resource (locations or service areas). Success criteria: geo capture used on a majority of new records within two weeks, no coordinate-quality issues reaching downstream consumers, and an explicit go/no-go on geocoding and tile hosting before any customer-facing use.