From 40d4a2431e40f7151578fa19fad139daa1cfd457 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mikl=C3=B3s=20Fazekas?= Date: Tue, 27 Oct 2026 10:30:04 +0100 Subject: [PATCH] docs(example): add snackSupported example metadata, mark 9 more examples webSupported snackSupported defaults to webSupported and is emitted to the example doc front matter as snack_supported, so maps-docs can show an "Edit in Snack" link without keeping its own allowlist. GeoJSONSource and ImageOverlay opt out since Snack can't load their PNG assets. --- AGENTS.md | 2 +- docs/examples.json | 33 ++++++++++++------- .../src/examples/Annotations/MarkerView.tsx | 1 + .../Annotations/MarkerViewPlacement.tsx | 1 + .../src/examples/Camera/ViewportGestures.tsx | 1 + .../examples/FillRasterLayer/GeoJSONSource.js | 2 ++ .../examples/FillRasterLayer/ImageOverlay.js | 2 ++ .../examples/Map/CameraGestureObserver.tsx | 1 + example/src/examples/Map/SetLanguage.tsx | 1 + .../src/examples/Map/ShowMapLocalStyle.tsx | 1 + example/src/examples/Map/StyleJson.js | 1 + .../SymbolCircleLayer/ScalableImages.tsx | 1 + example/src/examples/V10/GlobeProjection.tsx | 1 + .../src/examples/common/ExampleMetadata.ts | 2 ++ scripts/example-docs.ts | 3 +- 15 files changed, 40 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a16750ed7f..f8db0c7d99 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -121,7 +121,7 @@ The project uses Mapbox Maps SDK v11 and React Native's New Architecture (Fabric - Examples with JS timers or animations that block Detox sync should set `disableSync: true` in their metadata - Examples whose maps never go idle (following the user location, continuous animations) should set `waitForMapIdle: false` in their metadata, so the screenshot is taken after a fixed delay instead of the 20 s idle timeout - Examples whose screenshot isn't the same on every run (animations, label placement, random data) should set `excludeFromPercy: true` in their metadata to keep them out of the nightly Percy build -- Examples that work in the web build of the example app should set `webSupported: true` in their metadata; their doc page then links to the example in the hosted web app (https://rnmapbox.github.io/example-app/) +- Examples that work in the web build of the example app should set `webSupported: true` in their metadata; their doc page then links to the example in the hosted web app (https://rnmapbox.github.io/example-app/). The "Edit in Snack" link follows `webSupported` too; set `snackSupported` only where Snack differs from the web example app - See CONTRIBUTING.md for build and run instructions ### Documentation diff --git a/docs/examples.json b/docs/examples.json index d7a5ad9e10..009d672cae 100644 --- a/docs/examples.json +++ b/docs/examples.json @@ -145,7 +145,8 @@ "Images#stretchY", "Images#content" ], - "docs": "\nDemonstrates Scalable images.\n\nYou can use stretchX, stretchY and content to scale a bitmap image - keep parts of it fixed while only scale specific parts.\n" + "docs": "\nDemonstrates Scalable images.\n\nYou can use stretchX, stretchY and content to scale a bitmap image - keep parts of it fixed while only scale specific parts.\n", + "webSupported": true }, "fullPath": "example/src/examples/SymbolCircleLayer/ScalableImages.tsx", "relPath": "SymbolCircleLayer/ScalableImages.tsx", @@ -295,7 +296,8 @@ "CameraGestureObserver#maxIntervalMs", "CameraGestureObserver#onCameraChanged" ], - "docs": "\nDemonstrates how to detect when the map becomes steady after user gestures (pan, zoom, rotate). The CameraGestureObserver component fires the onMapSteady event after a configurable quiet period, providing information about the last gesture type and idle duration. onCameraChanged reports whether the camera is moving because of the user.\n" + "docs": "\nDemonstrates how to detect when the map becomes steady after user gestures (pan, zoom, rotate). The CameraGestureObserver component fires the onMapSteady event after a configurable quiet period, providing information about the last gesture type and idle duration. onCameraChanged reports whether the camera is moving because of the user.\n", + "webSupported": true }, "fullPath": "example/src/examples/Map/CameraGestureObserver.tsx", "relPath": "Map/CameraGestureObserver.tsx", @@ -436,7 +438,8 @@ "tags": [ "Mapbox#setLanguage" ], - "docs": "\nSets the label language for all maps in the app with `Mapbox.setLanguage`, which works with any language Mapbox supports and with the Standard style.\n" + "docs": "\nSets the label language for all maps in the app with `Mapbox.setLanguage`, which works with any language Mapbox supports and with the Standard style.\n", + "webSupported": true }, "fullPath": "example/src/examples/Map/SetLanguage.tsx", "relPath": "Map/SetLanguage.tsx", @@ -492,7 +495,8 @@ "title": "Show Map Local Style", "tags": [], "docs": "\nCustomize ornaments of the map(logo, compass, scalebar, attribution)\n", - "waitForMapIdle": false + "waitForMapIdle": false, + "webSupported": true }, "fullPath": "example/src/examples/Map/ShowMapLocalStyle.tsx", "relPath": "Map/ShowMapLocalStyle.tsx", @@ -532,7 +536,8 @@ "tags": [ "Style#json" ], - "docs": "\nChange style of a MapView on the fly.\n" + "docs": "\nChange style of a MapView on the fly.\n", + "webSupported": true }, "fullPath": "example/src/examples/Map/StyleJson.js", "relPath": "Map/StyleJson.js", @@ -622,7 +627,8 @@ "tags": [ "MapView#projection" ], - "docs": "\nShows map with globe projection\n" + "docs": "\nShows map with globe projection\n", + "webSupported": true }, "fullPath": "example/src/examples/V10/GlobeProjection.tsx", "relPath": "V10/GlobeProjection.tsx", @@ -748,7 +754,8 @@ "Interactive", "pointerEvents" ], - "docs": "\nShows marker view and point annotations, including an interactive marker with\nsliders, switch, counter, text input, and pressable button to verify complex\ntouch interactions inside a MarkerView. Toggle pointerEvents=\"none\" to make\nthe marker transparent to all touch events, passing them through to the map.\n" + "docs": "\nShows marker view and point annotations, including an interactive marker with\nsliders, switch, counter, text input, and pressable button to verify complex\ntouch interactions inside a MarkerView. Toggle pointerEvents=\"none\" to make\nthe marker transparent to all touch events, passing them through to the map.\n", + "webSupported": true }, "fullPath": "example/src/examples/Annotations/MarkerView.tsx", "relPath": "Annotations/MarkerView.tsx", @@ -763,7 +770,8 @@ "MarkerView#minZoom", "MarkerView#allowZElevate" ], - "docs": "\nTwo overlapping markers where `priority` picks the one that is shown, a marker hidden\nbelow `minZoom`, and a marker on a 3D building that `allowZElevate` lifts to the roof.\n" + "docs": "\nTwo overlapping markers where `priority` picks the one that is shown, a marker hidden\nbelow `minZoom`, and a marker on a 3D building that `allowZElevate` lifts to the roof.\n", + "webSupported": true }, "fullPath": "example/src/examples/Annotations/MarkerViewPlacement.tsx", "relPath": "Annotations/MarkerViewPlacement.tsx", @@ -866,7 +874,8 @@ "title": "GeoJSON Source", "tags": [], "docs": "", - "webSupported": true + "webSupported": true, + "snackSupported": false }, "fullPath": "example/src/examples/FillRasterLayer/GeoJSONSource.js", "relPath": "FillRasterLayer/GeoJSONSource.js", @@ -896,7 +905,8 @@ "docs": "", "disableSync": true, "excludeFromPercy": true, - "webSupported": true + "webSupported": true, + "snackSupported": false }, "fullPath": "example/src/examples/FillRasterLayer/ImageOverlay.js", "relPath": "FillRasterLayer/ImageOverlay.js", @@ -1103,7 +1113,8 @@ "Viewport#transitionsToIdleUponUserInteraction" ], "docs": "\nFollows a simulated moving location, and chooses which gestures stop following with `transitionsToIdleUponUserInteraction`.\n\nIn the object form, pan stops following, while zooming, rotating and pitching keep following and keep the user's value.\n", - "disableSync": true + "disableSync": true, + "webSupported": true }, "fullPath": "example/src/examples/Camera/ViewportGestures.tsx", "relPath": "Camera/ViewportGestures.tsx", diff --git a/example/src/examples/Annotations/MarkerView.tsx b/example/src/examples/Annotations/MarkerView.tsx index b98c92626f..6db00c9ed0 100644 --- a/example/src/examples/Annotations/MarkerView.tsx +++ b/example/src/examples/Annotations/MarkerView.tsx @@ -465,5 +465,6 @@ sliders, switch, counter, text input, and pressable button to verify complex touch interactions inside a MarkerView. Toggle pointerEvents="none" to make the marker transparent to all touch events, passing them through to the map. `, + webSupported: true, }; ShowMarkerView.metadata = metadata; diff --git a/example/src/examples/Annotations/MarkerViewPlacement.tsx b/example/src/examples/Annotations/MarkerViewPlacement.tsx index f80ab575a5..55a7041450 100644 --- a/example/src/examples/Annotations/MarkerViewPlacement.tsx +++ b/example/src/examples/Annotations/MarkerViewPlacement.tsx @@ -128,5 +128,6 @@ const metadata = { Two overlapping markers where \`priority\` picks the one that is shown, a marker hidden below \`minZoom\`, and a marker on a 3D building that \`allowZElevate\` lifts to the roof. `, + webSupported: true, }; MarkerViewPlacement.metadata = metadata; diff --git a/example/src/examples/Camera/ViewportGestures.tsx b/example/src/examples/Camera/ViewportGestures.tsx index a30daf6a1d..ad187aab2a 100644 --- a/example/src/examples/Camera/ViewportGestures.tsx +++ b/example/src/examples/Camera/ViewportGestures.tsx @@ -150,5 +150,6 @@ Follows a simulated moving location, and chooses which gestures stop following w In the object form, pan stops following, while zooming, rotating and pitching keep following and keep the user's value. `, disableSync: true, + webSupported: true, }; ViewportGestures.metadata = metadata; diff --git a/example/src/examples/FillRasterLayer/GeoJSONSource.js b/example/src/examples/FillRasterLayer/GeoJSONSource.js index e307d1921e..ef8794c1fc 100755 --- a/example/src/examples/FillRasterLayer/GeoJSONSource.js +++ b/example/src/examples/FillRasterLayer/GeoJSONSource.js @@ -68,5 +68,7 @@ const metadata = { tags: [], docs: '', webSupported: true, + // Snack can't load the example's PNG assets from a URL + snackSupported: false, }; GeoJSONSource.metadata = metadata; diff --git a/example/src/examples/FillRasterLayer/ImageOverlay.js b/example/src/examples/FillRasterLayer/ImageOverlay.js index 825da95bf4..6cb7939530 100755 --- a/example/src/examples/FillRasterLayer/ImageOverlay.js +++ b/example/src/examples/FillRasterLayer/ImageOverlay.js @@ -123,5 +123,7 @@ const metadata = { disableSync: true, excludeFromPercy: true, webSupported: true, + // Snack can't load the example's PNG assets from a URL + snackSupported: false, }; ImageOverlay.metadata = metadata; diff --git a/example/src/examples/Map/CameraGestureObserver.tsx b/example/src/examples/Map/CameraGestureObserver.tsx index 4d32f303bd..4639de67a7 100644 --- a/example/src/examples/Map/CameraGestureObserver.tsx +++ b/example/src/examples/Map/CameraGestureObserver.tsx @@ -123,5 +123,6 @@ const metadata: ExampleWithMetadata['metadata'] = { docs: ` Demonstrates how to detect when the map becomes steady after user gestures (pan, zoom, rotate). The CameraGestureObserver component fires the onMapSteady event after a configurable quiet period, providing information about the last gesture type and idle duration. onCameraChanged reports whether the camera is moving because of the user. `, + webSupported: true, }; CameraGestureObserverExample.metadata = metadata; diff --git a/example/src/examples/Map/SetLanguage.tsx b/example/src/examples/Map/SetLanguage.tsx index f8f9e6de81..fa076ca252 100644 --- a/example/src/examples/Map/SetLanguage.tsx +++ b/example/src/examples/Map/SetLanguage.tsx @@ -56,5 +56,6 @@ const metadata: ExampleWithMetadata['metadata'] = { docs: ` Sets the label language for all maps in the app with \`Mapbox.setLanguage\`, which works with any language Mapbox supports and with the Standard style. `, + webSupported: true, }; SetLanguage.metadata = metadata; diff --git a/example/src/examples/Map/ShowMapLocalStyle.tsx b/example/src/examples/Map/ShowMapLocalStyle.tsx index eb0bf759e9..325a04c8d7 100644 --- a/example/src/examples/Map/ShowMapLocalStyle.tsx +++ b/example/src/examples/Map/ShowMapLocalStyle.tsx @@ -40,5 +40,6 @@ const metadata: ExampleWithMetadata['metadata'] = { Customize ornaments of the map(logo, compass, scalebar, attribution) `, waitForMapIdle: false, + webSupported: true, }; ShowMap.metadata = metadata; diff --git a/example/src/examples/Map/StyleJson.js b/example/src/examples/Map/StyleJson.js index 9276b4eeec..69f0aae9a6 100755 --- a/example/src/examples/Map/StyleJson.js +++ b/example/src/examples/Map/StyleJson.js @@ -62,5 +62,6 @@ const metadata = { docs: ` Change style of a MapView on the fly. `, + webSupported: true, }; StyleJson.metadata = metadata; diff --git a/example/src/examples/SymbolCircleLayer/ScalableImages.tsx b/example/src/examples/SymbolCircleLayer/ScalableImages.tsx index d7ce3aa4db..f8a9465ed0 100644 --- a/example/src/examples/SymbolCircleLayer/ScalableImages.tsx +++ b/example/src/examples/SymbolCircleLayer/ScalableImages.tsx @@ -86,6 +86,7 @@ Demonstrates Scalable images. You can use stretchX, stretchY and content to scale a bitmap image - keep parts of it fixed while only scale specific parts. `, + webSupported: true, }; (ScaleableImages as unknown as ExampleWithMetadata).metadata = metadata; diff --git a/example/src/examples/V10/GlobeProjection.tsx b/example/src/examples/V10/GlobeProjection.tsx index 021edcdedc..e99031758f 100644 --- a/example/src/examples/V10/GlobeProjection.tsx +++ b/example/src/examples/V10/GlobeProjection.tsx @@ -81,5 +81,6 @@ const metadata: ExampleWithMetadata['metadata'] = { docs: ` Shows map with globe projection `, + webSupported: true, }; GlobeProjection.metadata = metadata; diff --git a/example/src/examples/common/ExampleMetadata.ts b/example/src/examples/common/ExampleMetadata.ts index b8bcaec52e..94b2eb6256 100644 --- a/example/src/examples/common/ExampleMetadata.ts +++ b/example/src/examples/common/ExampleMetadata.ts @@ -6,6 +6,8 @@ export type ExampleMetadata = { waitForMapIdle?: boolean; excludeFromPercy?: boolean; webSupported?: boolean; + /** Whether the docs show an "Edit in Snack" link; defaults to `webSupported`. */ + snackSupported?: boolean; }; export type ExampleWithMetadata = React.ComponentType & { diff --git a/scripts/example-docs.ts b/scripts/example-docs.ts index 8276fc2829..1ef1a1b538 100644 --- a/scripts/example-docs.ts +++ b/scripts/example-docs.ts @@ -38,7 +38,7 @@ examples.forEach(({ groupName, examples: _examples, metadata: _metadata }) => { return; } - const { title, tags, docs, webSupported } = metadata; + const { title, tags, docs, webSupported, snackSupported } = metadata; let jscode: string = fs.readFileSync( path.join(mapsRootPath, fullPath), @@ -85,6 +85,7 @@ title: ${title} tags: [${tags.join(', ')}] custom_props: example_rel_path: ${relPath} + snack_supported: ${snackSupported ?? webSupported ?? false} custom_edit_url: https://github.com/rnmapbox/maps/tree/master/example/src/examples/${relPath} --- ${docs}${webLink}