Filament Leaflet Laravel Package

Product Decisions This Supports

• Build vs. buy for location UX. This package covers the recurring "pick a point on a map and save it" problem in Filament admin panels — map widget, GeoSearch typeahead, and a Coordinate model cast — so the team buys a solved problem instead of re-implementing Leaflet integration per project.
• Feature scoping for location-aware admin flows. v5.2.2 makes the GeoSearch input reliable when a user clicks a specific result (previously it could select the last result in the list), so features like store locators, delivery-zone assignment, service-area setup, and property/asset geocoding can be specced with confidence rather than with caveats.
• Data-model decisions around address storage. The new coordinateLabelUsing() callback and the latitude/longitude label fallback let us choose between storing raw coordinates only, or persisting a human-readable label/address resolved by our own reverse-geocoding logic — a product decision about data ownership, third-party API cost, and display quality, now with first-class support either way.
• UI consistency commitments. Honoring textMode(true) and restoring labels for saved results means existing records render legibly in read-only/table contexts; this removes a class of "we need to fix the display of saved locations" backlog items.
• Roadmap optionality. Scalar JSON for select values (with PHP callbacks still receiving GeoSearchResult objects) means we can extend selection handling in application code without forking the package.
• Risk posture. This is a patch release on a maintained line: correctness fixes, explicit validation of the GeoSearch round trip through the Coordinate cast, and a successful production asset build. No breaking changes and no deprecations, so it can be adopted inside an existing sprint with no migration or upgrade project.

When to Consider This Package

Adopt it when:

• The product runs on Filament (v3/v4-era admin panels) and needs map input, map display, or coordinate persistence inside Filament forms/tables.
• Leaflet specifically is acceptable or preferred — i.e., you want an open-source map stack with tile providers you control, not Google Maps or Mapbox branding/billing.
• You need search-as-you-type geocoding wired into a form field, and you're comfortable supplying your own search/reverse-lookup callbacks (this package orchestrates the UI; your app owns the geocoding provider and its quotas/costs).
• You want coordinate persistence as a model cast, including custom cast columns and tolerance for legacy/invalid stored data (explicitly improved here).
• You value low integration surface: one plugin registration plus a form component, versus a bespoke Leaflet + livewire + validation stack.

Look elsewhere when:

• The stack isn't Filament (plain Blade/Livewire, Inertia/Vue, or a public-facing storefront map) — the value is concentrated in the Filament form/field integration.
• You require first-party Google Places/Mapbox search quality, autocomplete bias-by-viewport, or vendor SLAs; a thin Leaflet wrapper plus your own geocoder contract puts provider governance on you.
• You need heavy geospatial product features — polygon drawing/editing, routing/directions, clustering at scale, offline or static map rendering, or server-side spatial queries (PostGIS). This is a field-level map input, not a GIS platform.
• You need a guaranteed long-term support contract; this is a single-maintainer community package, so pin versions and keep a thin abstraction around the coordinate field.
• Your compliance posture requires audited tile-provider licensing (OSM usage policy, attribution, rate limits) — that's your responsibility regardless, but a commercial map vendor may be the simpler procurement story.

How to Pitch It (Stakeholders)

For executives: Location picking is a feature nearly every operational tool needs and nobody wants to fund twice. This package gives us a map + address search field in Filament out of the box, so location features ship in days rather than weeks, and we avoid maintaining our own map code. The latest release (v5.2.2) is a maintenance patch — it fixes a real user-facing bug where clicking a search result could save the wrong location, and it makes saved coordinates display with readable address labels. No breaking changes, no migration, no added vendor cost beyond the geocoding and tile providers we already choose and control.

For engineering: Patch release, drop-in upgrade from 5.2.x. Notable behavioral clarifications worth knowing: select values are now scalar JSON while PHP callbacks still receive GeoSearchResult objects (so don't assume the old value shape in custom field logic), textMode(true) is now honored, saved coordinates fall back to a lat/lng label unless you supply coordinateLabelUsing() for a stored address or your own reverse lookup, custom coordinate cast columns are respected, and invalid stored coordinate data is handled more defensively. Leaflet pane stacking (including tooltip panes) is corrected and the asset build passed. Recommended action: bump the dependency, re-run the GeoSearch round-trip test through our Coordinate cast, and verify any custom callbacks against the new value shape. Keep the version pinned and consider a thin internal wrapper around the field so a future maintainer change isn't a migration event.