Modern maps API: vector MapView + build-hint-wired NativeMap providers#5264
Modern maps API: vector MapView + build-hint-wired NativeMap providers#5264shai-almog wants to merge 22 commits into
Conversation
…iders Replaces the deprecated tile-based MapComponent / external google-maps cn1lib with a modern com.codename1.maps API: - MapView: pure-vector map rendered entirely via Graphics (MVT engine built on ProtoReader/GZIP, GeneralPath/Stroke), no native peer. Tile sources (Raster OSM, MVT, bundled, demo) and styles (light/dark, MapLibre-subset JSON). - NativeMap: native-provider map (Apple MapKit, Google, ...) selected by the maps.provider build hint, falling back to an embedded MapView when no provider is wired in or available. Provider impls are injected by the builders (MapsProviderInjector) so the core carries no map SDK and the API never names a provider. - Shared MapSurface API (camera, markers, polylines/polygons/circles, listeners, coordinate conversion); clean LatLng/MapBounds/CameraPosition value types. - iOS Apple MapKit provider verified end-to-end on the simulator (builds, links, renders) via the maps.provider=apple hint; Android Google provider template. - Full unit-test coverage in core-unittests, developer-guide chapter, and hellocodenameone screenshot tests (deterministic offline DemoTileSource). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Developer Guide build artifacts are available for download from this workflow run:
Developer Guide quality checks: |
Android screenshot updatesCompared 135 screenshots: 130 matched, 5 missing references.
Native Android coverage
Benchmark ResultsDetailed Performance Metrics
|
Native Windows port (cross-compiled)Compared 131 screenshots: 126 matched, 5 missing references.
Benchmark ResultsDetailed Performance Metrics
|
JavaScript port screenshot updatesCompared 127 screenshots: 122 matched, 5 missing references.
|
Native Linux port (x64)Compared 133 screenshots: 128 matched, 5 missing references.
|
Native Linux port (arm64)Compared 133 screenshots: 128 matched, 5 missing references.
|
Cloudflare Preview
|
|
Compared 210 screenshots: 210 matched. |
iOS screenshot updatesCompared 131 screenshots: 130 matched, 1 missing reference.
Benchmark Results
Build and Run Timing
Detailed Performance Metrics
|
iOS Metal screenshot updatesCompared 135 screenshots: 129 matched, 1 updated, 5 missing references.
Benchmark Results
Build and Run Timing
Detailed Performance Metrics
|
… docs
- MapView now defaults to the free, keyless OpenFreeMap vector basemap (real
OpenStreetMap data) instead of synthetic/raster, so vector maps render real
data with zero configuration and no API key.
- HttpTileSource resolves TileJSON endpoints (URLs with no {z} token) on first
use, supporting OpenFreeMap's versioned tile URLs (and any TileJSON source).
- Add MvtTileSource.openFreeMap() factory.
- Add a real-OSM screenshot test backed by a bundled San Francisco tile fixture
(real OpenFreeMap tiles) so the baseline shows real streets/water/labels yet
stays deterministic and offline. Verified rendering on the iOS simulator.
- Add docs/maps-provider-ci-setup.md: how native-provider (Apple/Google) tests
work, creating Google Maps keys, and wiring them as GitHub Actions secrets.
- Extra unit tests for the OpenFreeMap and raster OSM sources.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mac native screenshot updatesCompared 129 screenshots: 58 matched, 71 missing actuals.
Benchmark Results
|
Adds NativeMapProviderScreenshotTest: visual confirmation that a native map provider actually renders, catching "builds and launches but draws nothing" failures a smoke build misses. - Low-variance scene (Italian peninsula + Mediterranean at regional zoom): stable geography, strong land/water contrast, no traffic/street churn. - Emits a screenshot only when a native provider is active (isNativeMap()); NativeMapFallbackScreenshotTest is its complement and skips when a provider is active, so exactly one runs per platform/build. - The test app sets ios.maps.provider=apple, so the iOS device-runner captures a real MapKit baseline with no secret (verified on the simulator). - Lenient per-platform .tolerance (maxChannelDelta=20, maxMismatchPercent=12) absorbs tile/label noise but still fails on a blank/blocked map. - docs/maps-provider-ci-setup.md: the screenshot-test design plus key-generation walkthroughs for Apple (none), Google, Huawei (HMS) and Bing, with secret names and which providers are screenshot-testable vs smoke-only in CI. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Address all failing checks on the modern-maps PR: - SpotBugs (build-test): replace Number ctors with valueOf across the maps + maps/vector classes (DM_NUMBER_CTOR/DM_FP_NUMBER_CTOR/ DM_BOOLEAN_CTOR); rewrite LatLng longitude wrap with modulo instead of a float loop (FL_FLOATS_AS_LOOP_COUNTERS); make VectorMapEngine.tileSize static (SS_SHOULD_BE_STATIC); reference the enclosing instance in BundledTileSource's fetch Runnable (SIC_INNER_SHOULD_BE_STATIC_ANON, also fixes the latent getClass() resource-resolution); exclude EQ_DOESNT_OVERRIDE_EQUALS for the one-shot HttpTileSource ConnectionRequest subclasses. - build-javadocs: add package-info.java for com.codename1.maps.spi and com.codename1.maps.vector (flagged by check-package-info.sh). - Developer guide prose: contractions / "for example" / drop "freely" for Vale; add basemap/basemaps/Mapbox to the LanguageTool accept list. - build-ios / build-ios-metal / build-mac-native: the native screenshot suite hung on NativeMap creation because AppleMapProvider.m's nativeCreate did dispatch_sync to the main queue, which deadlocks when the CN1 iOS EDT already runs on the main thread. Create inline when already on the main thread. - build-ios-watch: MKMapView and the overlay renderers are unavailable on watchOS; guard the MapKit impl with TARGET_OS_WATCH and provide linkable no-op stubs (nativeCreate returns 0 -> NativeMap falls back to the vector MapView). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The build-test quality gate flagged PMD forbidden rules across the new maps classes (SpotBugs already passed): - MissingOverride (x105): annotate every override -- interface impls, equals/hashCode/toString and Runnable.run() -- matching the core convention (e.g. CodenameOneImplementation annotates interface run()). - ForLoopCanBeForeach (x28): convert index loops over lists/arrays to enhanced-for, with distinct loop variables to avoid nested shadowing. - EmptyCatchBlock (x2): give the malformed-input catches an explicit return instead of a bare comment. - AvoidUsingVolatile (x1): drop volatile from HttpTileSource .resolvedTemplate and read it under the existing monitor, which also keeps SpotBugs IS2_INCONSISTENT_SYNC satisfied. - UnnecessaryImport (x1): remove the unused ActionListener import. - UnusedFormalParameter (x1): drop MvtDecoder.decodeGeometry's unused geometry-type argument. Verified locally on JDK 8: compiles, SpotBugs check passes with 0 bugs, 0 forbidden PMD violations across core, 0 Checkstyle errors, 3544 tests green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The iOS/Mac screenshot suites crashed (SIGABRT / doesNotRecognizeSelector) when NativeMap showed its native MapKit peer. Root cause: the peer was built in the constructor, detached from any form, then laid out on show, which UIKit/MapKit rejects. Fix: resolve the provider in the constructor (cheap, no peer) and create the vector fallback eagerly only when there is no provider; create the native peer lazily once the component is attached -- in initComponent(), deferred via callSerially so it runs after the form is shown rather than re-entering layout mid-attach. Markers added before the peer existed are replayed, and the post-show revalidate is guarded on a non-null form. Verified on the iOS simulator: the suite now runs to completion (CN1SS:SUITE:FINISHED) with no native crash; NativeMapFallback skips cleanly when a provider is active (the earlier NullPointerException is gone). Compiles on JDK 8 with SpotBugs (0 bugs) and 0 forbidden PMD. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The watchOS screenshot job has no committed map goldens, so the six map screenshots that render on the watch (the vector MapView tests plus the NativeMap vector fallback) were streamed as missing_expected and failed the watch run, which tolerates zero missing goldens. Map coverage is meaningful on the phone/tablet form factors; skip these tests on the watch via CN.isWatch() so the watch suite stays green. NativeMapProvider already self-skips on the watch (no native provider -> not isNativeMap()). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
✅ Continuous Quality ReportTest & Coverage
Static Analysis
Generated automatically by the PR CI workflow. |
invalidate() (called from native code when the peer's size changes) did getComponentForm().revalidate() with no null check. When a native peer is added to a container that isn't fully wired to a form yet -- e.g. a NativeMap peer installed after the form is shown -- getComponentForm() returns null and the unguarded call NPEs on the EDT. Null-check the form before revalidating; an invalidate with no form is a no-op. Verified on the iOS simulator: with this guard the NativeMap MapKit peer is added without the previous addComponent-time NullPointerException. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
On the watch the provider is registered and reports available, so the test did not self-skip via isNativeMap(); it then fell back to the vector map and streamed a NativeMapProvider screenshot with no committed watch golden, failing build-ios-watch (which tolerates zero missing goldens). The iOS phone/metal jobs already pass. Skip explicitly on CN.isWatch(), matching the other map screenshot tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Visual-quality pass on the map rendering:
- Default markers now draw the standard Material Design map pin
(FontImage.MATERIAL_PLACE) anchored at the tip, instead of a plain dot,
matching platform conventions.
- StyleLayer gains an excludeFilter(); the light/dark styles exclude
class=ferry from the transportation layer so ferry routes are no longer
drawn as roads running across the bay ("lines into the sea").
- The vector screenshot tests now render the bundled real San Francisco
OSM tiles (dark style, SF-landmark markers, and a route/area/radius
shape set) instead of the synthetic "CN1 city" demo tileset, which
looked weird and tiled the same block repeatedly. The redundant
VectorMapBasemap test is removed (RealOsmVector already covers the
light real basemap). NativeMap's vector fallback uses the real tiles too.
Marker rendering verified on the iOS simulator; the tile/style changes
render on the CI device runners (the bundled tiles do not load on the
local simulator due to its flattened resource layout).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two fixes that make the Apple MapKit NativeMap actually render: 1. Lay the peer out (revalidate the form to give it a non-zero frame) before doing anything else, and never let a post-show provider call abort installation -- previously an exception left the peer 0-sized and invisible. 2. Set the map's initial region when the native peer is created rather than via a separate setCamera() call after attach. createPeer now reads the host's initial center/zoom (new package-private NativeMap.getInitialCenter/getInitialZoom) and passes them into nativeCreate, which applies the MKCoordinateRegion as the MKMapView is built. Verified on the iOS simulator: NativeMapProvider renders a real Apple Maps view centered on the configured region (Italy / the Mediterranean at the test's 41,13 zoom 5), ~2MB of map content, instead of a blank panel. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Apple MapKit (and future Google) native map renders live imagery that varies run-to-run; widen the tolerance (and add it to the Metal/Mac backends) so it tolerates tile/label noise while still failing on a blank or blocked map. Triggers a fresh native + vector render for golden capture. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The iOS build flattens app resources, so maptiles/13/{x}/{y}.mvt collapsed
to {y}.mvt at the bundle root and the three x-column tiles collided to a
single file -- the same tile then loaded for every column, replicating the
map horizontally (the "same data repeated" artifact). Rename the fixtures
to unique flat basenames (mt_{z}_{x}_{y}.mvt) and update the bundled tile
source path templates, so each column loads its own tile on iOS while
JavaSE/Android (which keep the directory structure) still resolve fine.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
MVT tiles carry features in a buffer beyond the 0..extent tile bounds so adjacent geometry joins cleanly. Place labels anchored in that buffer were being emitted, so on a small fixture tileset they floated in the empty background past the loaded coverage. Skip labels whose anchor is outside the tile's own bounds; the neighbouring tile (when present) renders them. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the CI-rendered iOS goldens for the vector map screenshot tests
(RealOsmVector, VectorMapDarkStyle, VectorMapMarkers, VectorMapShapes)
with a small AA-tolerant .tolerance each, so they are pixel-compared
("green images") instead of merely tolerated as new.
Illustrate the Maps developer-guide chapter with representative
screenshots: the vector basemap, the default Material map pins, the dark
style, and a NativeMap backed by Apple MapKit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Apple MapKit (and other native maps) stall on a location-permission prompt in the simulator, leaving the map a blank "grid" placeholder in CI. Grant the location privacy entitlement to the app and pin a fixed simulated coordinate right after install (before launch) so the native map loads its tiles, which makes the NativeMapProvider screenshot a real map. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the single "preferred provider" hint with an ordered fallback
chain: setProviderOrder("google","huawei","web") tries each in turn (first
available wins) before the vector fallback, with "vector"/"none" as an
explicit chain terminator. Drives sophisticated per-platform behavior from
the maps.providers / <platform>.maps.providers build hints and is fully
overridable from app code. setPreferredProvider is kept as a one-element
shorthand.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add com.codename1.maps.WebMapProvider, a MapProvider that hosts a JS map SDK (Google Maps JS via WebMapProvider.google) inside a BrowserComponent so any platform with a browser can render Google Maps -- the natural "web" entry in a provider fallback chain and the only way to surface SDKs with no native peer. Its initial camera is baked into the page from the host NativeMap's center/zoom so the map opens on the right region with no follow-up call. To carry web (BrowserComponent) and native (PeerComponent) peers uniformly the SPI MapProvider.createPeer now returns Component (covariant -- native providers returning PeerComponent still satisfy it); NativeMap.installPeer takes a Component. Add a GoogleWebMap screenshot test (frames Italy at a regional zoom like the native-provider test) gated on the GOOGLE_MAPS_API_KEY secret: the three build-*-app.sh scripts source scripts/lib/inject-maps-key.sh which materializes the key as a bundled, gitignored resource only when the secret is present; the test skips cleanly when it is absent (forks/local). The screenshot workflows pass the secret through. Azure/Huawei tests intentionally deferred. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…web"
CI confirmed the WebMapProvider Google JS map renders a real, label-rich
Google map of the Mediterranean on iOS (GL and Metal) and Android -- the key
works with no billing/dev watermark. Commit those three as goldens with a wide
tolerance (live tiles/labels shift run-to-run; still fails loudly on a blank or
key-blocked map). Mac native captures the web peer as black (a port screenshot
limitation), so it is intentionally left golden-less -- a new screenshot with
no golden is a non-failing missing_expected, so that job stays green.
Give WebMapProvider.google() the id "web" (not "google") so it slots in as the
cross-platform web fallback after the native "google" provider in a chain like
setProviderOrder("google", "web", "vector") instead of colliding with it.
Document the web provider and fallback-order customization in the maps guide
with a representative screenshot.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…suite Root-causes the iOS Metal flakiness this PR introduced. The GoogleWebMap test embeds a live BrowserComponent whose Google Maps JS runs a continuous requestAnimationFrame / tile-loading loop for the life of the page. Nothing tore it down, so it kept running in the background across the rest of the screenshot suite, starving the iOS main thread and intermittently desyncing later tests' capture timing -- e.g. the DesktopMode capture grabbed a stale OrientationLock form (proven by the artifact). metal was green on the commit before this test existed; it started failing on tests that run AFTER GoogleWebMap once it was added. Fix the underlying leak: add NativeMap.dispose() which detaches the peer and calls the provider's deinitialize(); WebMapProvider.deinitialize now blanks the BrowserComponent's page so the SDK's animation loop actually stops. The GoogleWebMap test disposes the map immediately after its capture, so no live web view survives into the rest of the suite. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The provider-teardown catch was comment-only, which the CI quality gate's PMD forbids (EmptyCatchBlock). Surface the failure with printStackTrace() instead of swallowing it silently. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 participant
Summary
Brings mapping back into core, modernized, replacing the deprecated tile-based
MapComponentand the externalcodenameone-google-mapscn1lib. Two components share oneMapSurfaceAPI:MapView— a pure-vector map rendered entirely throughGraphics(a new MVT engine built on the framework'sProtoReader+GZIPInputStream,GeneralPath/Stroke). No native peer, so it composes cleanly with CN1 UI and works identically everywhere (simulator, web). Pluggable tile sources (raster OSM default, MVT, bundled, demo) and styles (light/dark, MapLibre-subset JSON).NativeMap— a native-provider map (Apple MapKit, Google Maps, …) that falls back to an embeddedMapViewwhen no provider is wired in or available at runtime.Provider model — wired by build hints, not code
The public API never names a provider. A provider is selected with the
maps.providerbuild hint (apple/google/…); the builders (MapsProviderInjector) inject that provider's native-method-bearing implementation into the app'scom.codename1.mapspackage and wire it in — so core/ports carry no map SDK and unused providers cost zero project size. NoNativeInterface, noCodenameOneImplementationhooks.Verified
maps.provider=apple): builds, links, and renders a live MapKit map with a marker viaNativeMap.core-unittests(value types, model, provider SPI registry, MVT decoder incl. all value types, styles, color/zoom/cache internals, Web Mercator) — all green against a from-source build.Maps.asciidoc) and hellocodenameone screenshot tests (deterministic offlineDemoTileSource).A companion PR mirrors the builder injection into the BuildDaemon repo.
🤖 Generated with Claude Code