Statamic Simple Address Laravel Package

Product Decisions This Supports

• Shipping map/address UI without a vendor contract. v0.2.4 replaces the default CARTO tiles with OpenStreetMap, which removes the API-key-driven watermark on the default path. That turns "do we need a Maps budget line and a key-management owner?" into "no, by default" for basic address/location display.
• Build vs. buy vs. adopt. This is a small, free, single-purpose Statamic addon. Adopting it is the cheap option versus building map rendering + address formatting in-house; the release lowers the cost of that decision because there is no third-party account to provision before a demo.
• Design and brand consistency. Provider-neutral light and dark tile layers are now configurable. Dark mode is a recurring stakeholder ask on marketing sites and portals, and "reuse the light layer when no dark layer is configured" means dark mode is supported even with a one-line config — useful when scoping dark-mode work.
• Roadmap sequencing. Because this is config-only and backward compatible with published configs, it can be folded into an existing release train rather than scheduled as its own upgrade epic. Low cost, visible end-user benefit.
• Vendor flexibility as a hedge. If legal or brand later mandates Mapbox, Stadia, or self-hosted tiles, the config surface already exists — you are not re-platforming to change map providers.
• Concrete use cases to scope against: store/office locators, contact and "find us" pages, distributor or partner directories, listing/detail pages in a Statamic-driven site, and any content type where an address block is authored by editors rather than developers.

When to Consider This Package

Consider it when:

• The site is already on Statamic (this is a Statamic addon, not a general Laravel package — confirm the stack before it enters a roadmap).
• Requirements are display-oriented: format and render a postal address, optionally with a map. Editors author addresses; you are not solving logistics.
• You want a zero-procurement default: no API key, no account, no per-request billing on the standard path as of v0.2.4.
• You need light/dark map styling with minimal configuration, or need to point at a specific tile provider for brand reasons.
• You are on a published config from an earlier version — this release is explicitly backward compatible, so upgrade cost is near zero.
• Traffic and page count are modest; static tile layers are cheap, but this is not a mapping platform.

Look elsewhere (or plan additional engineering) when:

• You need geocoding, address validation/autocomplete, routing, directions, distance search, or marker clustering — those are separate services, not this package.
• Privacy/GDPR posture is strict. Any third-party tile layer (OSM included) means visitor IPs and viewport data hit an external server. If that is a blocker, budget for self-hosted tiles and evaluate whether the package's config surface covers your setup.
• You need an SLA, paid support, or a security review trail. This is a v0.x, single-maintainer open-source addon; treat it as a dependency with maintenance risk, not a supported product.
• You require stable public APIs across a multi-year roadmap. Pre-1.0 versioning means breaking changes are plausible in future releases; pin versions and read changelogs.
• Map-heavy, high-traffic pages are core to the product — you likely want a dedicated mapping SDK and a tile agreement.

Compliance note worth assigning an owner: OpenStreetMap's default tiles carry attribution requirements. Using the default is fine for typical marketing pages, but the attribution must stay visible.

How to Pitch It (Stakeholders)

For executives (one paragraph): This release makes our address and map display work without any vendor account, API key, or maps line item — we removed the default mapping provider that was stamping a watermark and now ship on OpenStreetMap. It also adds light and dark map styling through configuration, so dark mode is covered without extra build work. The upgrade is backward compatible with our existing settings, meaning it is a low-risk change we can absorb into the current release rather than a standalone project. Net: a small, free dependency doing a small, well-defined job, with the main caveat being that it is a pre-1.0 community addon rather than a supported commercial product.

For engineering: Config-driven tile layers via config/simple-address.php, provider-neutral, with fallback from dark to light when no dark layer is set; default switched from CARTO to OSM, eliminating the API key requirement. Published configs remain compatible — verify attribution rendering and run a visual check of both themes, then pin the version.

For design/UX: Dark mode map support is now a config change rather than a code change, and the map provider can be swapped without rework if brand styling demands it.

Risk to state plainly: single maintainer, v0.x versioning, and an external tile dependency that carries attribution and visitor-IP considerations. Mitigations are version pinning and a documented fallback provider — both cheap.