diff --git a/docs/api-reference/components/static-map.md b/docs/api-reference/components/static-map.md new file mode 100644 index 00000000..f553d22e --- /dev/null +++ b/docs/api-reference/components/static-map.md @@ -0,0 +1,229 @@ +# `` Component + +React component and utility function to create and render [Google Static Maps][gmp-static-map] images. This implementation provides both a React component for rendering and a URL generation utility that supports all Google Static Maps API features. The main purpose of the utility function is to enable 'url-signing' in various +server environments. + +The main parameters to control the map are `center`, +`zoom`, `width` and `height`. With a plain map all of these are required for the map to show. There are cases where `center` and `zoom` can be omitted and the viewport can be automatically be determined from other data. This is the case when having markers, paths or other `visible` locations which can form an automatic bounding box for the map view. + +Parameters that are always required are `apiKey`, `width` and `height`. + +```tsx +import {StaticMap, createStaticMapsUrl} from '@vis.gl/react-google-maps'; + +const App = () => { + let staticMapsUrl = createStaticMapsUrl({ + apiKey: 'YOUR API KEY', + width: 512, + height: 512, + center: {lat: 53.555570296010295, lng: 10.008892744638956}, + zoom: 15 + }); + + // Recommended url-signing when in a server environment. + staticMapsUrl = someServerSigningCode( + staticMapsUrl, + process.env.MAPS_SIGNING_SECRET + ); + + return ; +}; +``` + +More on URL signing and digital signatures [here](#digital-signature). + +## Props + +The `StaticMap` component only has one `url` prop. The recommended way to generate the url is to use the `createStaticMapsUrl` helper function. + +### Required + +#### `url`: string + +An url which can be consumed by the Google Maps Static Api. + +### Optional + +#### `className`: string + +A class name that will be attached to the `img` tag. + +## `createStaticMapsUrl` options + +:::note + +Some explanations and syntax migh differ slighty from the official documentation since the Google documentation focuses on building and URL which has +been abstracted here in the helper function for better developer experience + +::: + +For more details about API options see the [get started][get-started] guide in the Google documentation. + +### Required + +#### `apiKey`: string + +The Google Maps Api key. + +#### `width`: number + +Width of the image. Maps smaller than 180 pixels in width will display a reduced-size Google logo. This parameter is affected by the scale parameter; the final output size is the product of the size and scale values. + +#### `height`: number + +Height of the image. This parameter is affected by the scale parameter; the final output size is the product of the size and scale values. + +### Optional + +#### `center`: [StaticMapsLocation](#staticmapslocation) + +(required if no markers, paths or visible locations are present) Defines the center of the map, equidistant from all edges of the map. This parameter takes a location as either [`google.maps.LatLngLiteral`][gmp-ll] or a string address (e.g. "city hall, new york, ny") identifying a unique location on the face of the earth. + +#### `zoom`: number + +(required if no markers, paths or visible locations are present) Defines the zoom level of the map, which determines the magnification level of the map. This parameter takes a numerical value corresponding to the zoom level of the region desired. + +#### `scale`: number + +Affects the number of pixels that are returned. scale=2 returns twice as many pixels as scale=1 while retaining the same coverage area and level of detail (i.e. the contents of the map don't change). This is useful when developing for high-resolution displays. The default value is 1. Accepted values are 1 and 2 + +#### `format`: 'png' | 'png8' | 'png32' | 'gif' | 'jpg' | 'jpg-baseline' + +Defines the format of the resulting image. By default, the Maps Static API creates PNG images. There are several possible formats including GIF, JPEG and PNG types. Which format you use depends on how you intend to present the image. JPEG typically provides greater compression, while GIF and PNG provide greater detail + +#### `mapType`: [google.maps.MapTypeId][gmp-map-type-id] + +Defines the type of map to construct. There are several possible maptype values, including roadmap, satellite, hybrid, and terrain. + +#### `language`: string + +Defines the language to use for display of labels on map tiles. Note that this parameter is only supported for some country tiles; if the specific language requested is not supported for the tile set, then the default language for that tileset will be used. + +#### `region`: string + +Defines the appropriate borders to display, based on geo-political sensitivities. Accepts a region code specified as a two-character ccTLD ('top-level domain') value + +#### `mapId`: string + +Specifies the identifier for a specific map. The Map ID associates a map with a particular style or feature, and must belong to the same project as the API key used to initialize the map. + +#### `markers`: [StaticMapsMarker[]](#staticmapsmarker) + +Defines markers that should be visible on the map. + +#### `paths`: [StaticMapsPath[]](#staticmapspath) + +Defines paths that should be shown on the map. + +#### `visible`: [StaticMapsLocation[]](#staticmapslocation) + +Specifies one or more locations that should remain visible on the map, though no markers or other indicators will be displayed. Use this parameter to ensure that certain features or map locations are shown on the Maps Static API. + +#### `style`: [google.maps.MapTypeStyle[]][gmp-map-type-style] + +Defines a custom style to alter the presentation of a specific feature (roads, parks, and other features) of the map. This parameter takes feature and element arguments identifying the features to style, and a set of style operations to apply to the selected features. See [style reference][gmp-style-ref] for more information. + +## Digital Signature + +:::warning + +Please only use URL signing on the server and keep your URL signing secret secure. Do not pass it in any requests, store it on any websites, or post it to any public forum. Anyone obtaining your URL signing secret could spoof requests using your identity. + +::: +It is recommended to use a [digital signature][digital-signature] with your Static Maps Api requests. + +Digital signatures are generated using a URL signing secret, which is available on the Google Cloud Console. This secret is essentially a private key, only shared between you and Google, and is unique to your project. + +The signing process uses an encryption algorithm to combine the URL and your shared secret. The resulting unique signature allows our servers to verify that any site generating requests using your API key is authorized to do so. + +- Step 1: [Get your URL signing secret][sign-secret] +- Step 2: Construct an unsigned request with the `createStaticMapUrl` helper. +- Step 3: [Generate the signed request][generate-signed] | [Sample code for URL signing][sample-code] + +Google also provides a package [`@googlemaps/url-signature`][url-signature] for URL signing. Another example could look like this. Here in a Next.js environment. + +```tsx +import 'server-only'; + +import {signUrl} from '@googlemaps/url-signature'; + +export function signStaticMapsUrl(url: string, secret: string): string { + return signUrl(url, secret).toString(); +} +``` + +When the signing process is setup, you can then [limit the unsigned request][limit-unsigned] to prevent abuse of your api key + +## Types + +### StaticMapsLocation + +Reference: [`google.maps.LatLngLiteral`][gmp-ll] + +```tsx +type StaticMapsLocation = google.maps.LatLngLiteral | string; +``` + +### StaticMapsMarker + +- For `color`, `size`, `label` see [marker styles][gmp-marker-styles]. +- For `icon`, `anchor` and `scaling` see [custom icons][gmp-custom-icons]. + +```tsx +type StaticMapsMarker = { + location: google.maps.LatLngLiteral | string; + color?: string; + size?: 'tiny' | 'mid' | 'small'; + label?: string; + icon?: string; + anchor?: string; + scale?: 1 | 2 | 4; +}; +``` + +### StaticMapsPath + +For style options see [Path styles][gmp-path-styles]. + +`coordinates` can either bei an array of locations/addresses or it can be an [encoded polyline][gmp-encoded-polyline]. Note that the encoded polyline needs an `enc:` prefix. + +```tsx +type StaticMapsPath = { + coordinates: Array | string; + weight?: number; + color?: string; + fillcolor?: string; + geodesic?: boolean; +}; +``` + +## Examples + +Usage examples for many of the API options can be found [here][usage-examples] + +## Source + +[`./src/components/static-map`][static-map-source]\ +[`./src/libraries/create-static-maps-url/index`][create-static-map-url-source]\ +[`./src/libraries/create-static-maps-url/types`][create-static-map-url-types] + +[gmp-static-map]: https://developers.google.com/maps/documentation/maps-static +[static-map-source]: https://github.com/visgl/react-google-maps/tree/main/src/components/static-map +[create-static-map-url-source]: https://github.com/visgl/react-google-maps/tree/main/src/libraries/create-static-maps-url/index.ts +[create-static-map-url-types]: https://github.com/visgl/react-google-maps/tree/main/src/libraries/create-static-maps-url/types +[gmp-map-type-id]: https://developers.google.com/maps/documentation/javascript/reference/map#MapTypeId +[gmp-ll]: https://developers.google.com/maps/documentation/javascript/reference/coordinates#LatLngLiteral +[gmp-map-type-style]: https://developers.google.com/maps/documentation/javascript/reference/map#MapTypeStyle +[usage-examples]: https://github.com/visgl/react-google-maps/tree/main/examples/static-map +[get-started]: https://developers.google.com/maps/documentation/maps-static/start +[sign-secret]: https://developers.google.com/maps/documentation/maps-static/digital-signature#get-secret +[gmp-encoded-polyline]: https://developers.google.com/maps/documentation/maps-static/start#EncodedPolylines +[gmp-path-styles]: https://developers.google.com/maps/documentation/maps-static/start#PathStyles +[gmp-marker-styles]: https://developers.google.com/maps/documentation/maps-static/start#MarkerStyles +[gmp-custom-icons]: https://developers.google.com/maps/documentation/maps-static/start#CustomIcons +[limit-unsigned]: https://developers.google.com/maps/documentation/maps-static/digital-signature#limit-unsigned-requests +[url-signature]: https://www.npmjs.com/package/@googlemaps/url-signature +[generate-signed]: https://developers.google.com/maps/documentation/maps-static/digital-signature#generate-signed-request +[sample-code]: https://developers.google.com/maps/documentation/maps-static/digital-signature#sample-code-for-url-signing +[digital-signature]: https://developers.google.com/maps/documentation/maps-static/digital-signature +[gmp-style-ref]: https://developers.google.com/maps/documentation/maps-static/style-reference diff --git a/docs/table-of-contents.json b/docs/table-of-contents.json index dcd020eb..07a5ab0e 100644 --- a/docs/table-of-contents.json +++ b/docs/table-of-contents.json @@ -39,7 +39,8 @@ "api-reference/components/info-window", "api-reference/components/marker", "api-reference/components/advanced-marker", - "api-reference/components/pin" + "api-reference/components/pin", + "api-reference/components/static-map" ] }, { diff --git a/examples/examples.css b/examples/examples.css index 4aaa6b3d..060af367 100644 --- a/examples/examples.css +++ b/examples/examples.css @@ -126,3 +126,30 @@ html[data-theme='dark'] .gm-style { opacity: 0.5; cursor: default; } + +.static-map-grid, +.static-map-grid * { + box-sizing: border-box; +} + +.static-map-grid { + display: grid; + grid-template-rows: 1fr 1fr; + grid-template-columns: 1fr 1fr; + height: 100%; + width: 100%; + gap: 16px; + padding: 16px; + background: darkgray; +} + +.static-map-grid .map-container { + position: relative; +} + +.static-map-grid .map { + object-fit: contain; + position: absolute; + height: 100%; + width: 100%; +} diff --git a/examples/static-map/README.md b/examples/static-map/README.md new file mode 100644 index 00000000..294e7d06 --- /dev/null +++ b/examples/static-map/README.md @@ -0,0 +1,35 @@ +# Static Map Example + +This is an example to show how to use the `Static Map` component. + +## Google Maps Platform API Key + +This example does not come with an API key. Running the examples locally requires a valid API key for the Google Maps Platform. +See [the official documentation][get-api-key] on how to create and configure your own key. + +The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a +file named `.env` in the example directory with the following content: + +```shell title=".env" +GOOGLE_MAPS_API_KEY="" +``` + +If you are on the CodeSandbox playground you can also choose to [provide the API key like this](https://codesandbox.io/docs/learn/environment/secrets) + +## Development + +Go into the example-directory and run + +```shell +npm install +``` + +To start the example with the local library run + +```shell +npm run start-local +``` + +The regular `npm start` task is only used for the standalone versions of the example (CodeSandbox for example) + +[get-api-key]: https://developers.google.com/maps/documentation/javascript/get-api-key diff --git a/examples/static-map/index.html b/examples/static-map/index.html new file mode 100644 index 00000000..72dcb2cd --- /dev/null +++ b/examples/static-map/index.html @@ -0,0 +1,31 @@ + + + + + + Static Map Example + + + + +
+ + + diff --git a/examples/static-map/package.json b/examples/static-map/package.json new file mode 100644 index 00000000..05765f98 --- /dev/null +++ b/examples/static-map/package.json @@ -0,0 +1,14 @@ +{ + "type": "module", + "dependencies": { + "@vis.gl/react-google-maps": "latest", + "react": "^18.2.0", + "react-dom": "^18.2.0", + "vite": "^5.0.4" + }, + "scripts": { + "start": "vite", + "start-local": "vite --config ../vite.config.local.js", + "build": "vite build" + } +} diff --git a/examples/static-map/src/app.tsx b/examples/static-map/src/app.tsx new file mode 100644 index 00000000..d40d48b3 --- /dev/null +++ b/examples/static-map/src/app.tsx @@ -0,0 +1,42 @@ +import React from 'react'; +import {createRoot} from 'react-dom/client'; + +import StaticMap1 from './static-map-1'; +import StaticMap2 from './static-map-2'; +import StaticMap3 from './static-map-3'; +import StaticMap4 from './static-map-4'; + +import ControlPanel from './control-panel'; + +function App() { + return ( +
+
+ +
+
+ +
+
+ +
+
+ +
+ + +
+ ); +} + +export default App; + +export function renderToDom(container: HTMLElement) { + const root = createRoot(container); + + root.render( + + + + ); +} diff --git a/examples/static-map/src/control-panel.tsx b/examples/static-map/src/control-panel.tsx new file mode 100644 index 00000000..9998d657 --- /dev/null +++ b/examples/static-map/src/control-panel.tsx @@ -0,0 +1,25 @@ +import * as React from 'react'; + +function ControlPanel() { + return ( +
+

Static Map

+

Static Map usage examples.

+ +
+ ); +} + +export default React.memo(ControlPanel); diff --git a/examples/static-map/src/static-map-1.tsx b/examples/static-map/src/static-map-1.tsx new file mode 100644 index 00000000..e1f286c6 --- /dev/null +++ b/examples/static-map/src/static-map-1.tsx @@ -0,0 +1,19 @@ +import React from 'react'; +import {StaticMap, createStaticMapsUrl} from '@vis.gl/react-google-maps'; + +const API_KEY = + globalThis.GOOGLE_MAPS_API_KEY ?? (process.env.GOOGLE_MAPS_API_KEY as string); + +export default function StaticMap1() { + const staticMapsUrl = createStaticMapsUrl({ + apiKey: API_KEY, + scale: 2, + width: 600, + height: 600, + center: {lat: 53.555570296010295, lng: 10.008892744638956}, + zoom: 8, + language: 'en' + }); + + return ; +} diff --git a/examples/static-map/src/static-map-2.tsx b/examples/static-map/src/static-map-2.tsx new file mode 100644 index 00000000..cfafd379 --- /dev/null +++ b/examples/static-map/src/static-map-2.tsx @@ -0,0 +1,44 @@ +import React from 'react'; +import {StaticMap, createStaticMapsUrl} from '@vis.gl/react-google-maps'; + +const API_KEY = + globalThis.GOOGLE_MAPS_API_KEY ?? (process.env.GOOGLE_MAPS_API_KEY as string); + +export default function StaticMap2() { + const staticMapsUrl = createStaticMapsUrl({ + apiKey: API_KEY, + scale: 2, + width: 600, + height: 600, + mapId: '8e0a97af9386fef', + format: 'png', + markers: [ + { + location: 'Hamburg, Germany', + color: '0xff1493', + label: 'H', + size: 'small' + }, + { + location: {lat: 52.5, lng: 10}, + color: 'blue', + label: 'H' + }, + { + location: 'Berlin, Germany', + color: 'orange', + icon: 'http://tinyurl.com/jrhlvu6', + anchor: 'center', + label: 'B', + scale: 2 + }, + { + location: 'Essen, Germany', + color: 'purple' + } + ], + visible: ['Germany'] + }); + + return ; +} diff --git a/examples/static-map/src/static-map-3.tsx b/examples/static-map/src/static-map-3.tsx new file mode 100644 index 00000000..00093c9d --- /dev/null +++ b/examples/static-map/src/static-map-3.tsx @@ -0,0 +1,32 @@ +import React from 'react'; +import {StaticMap, createStaticMapsUrl} from '@vis.gl/react-google-maps'; + +const API_KEY = + globalThis.GOOGLE_MAPS_API_KEY ?? (process.env.GOOGLE_MAPS_API_KEY as string); + +export default function StaticMap3() { + const staticMapsUrl = createStaticMapsUrl({ + apiKey: API_KEY, + scale: 2, + width: 600, + height: 600, + mapType: 'hybrid', + format: 'jpg', + paths: [ + { + color: '0xff1493', + fillcolor: '0xffff00', + coordinates: [ + {lat: 52.5, lng: 10}, + 'Berlin, Germany', + 'Hamburg, Germany' + ] + }, + { + coordinates: [{lat: 52.5, lng: 10}, 'Leipzig, Germany'] + } + ] + }); + + return ; +} diff --git a/examples/static-map/src/static-map-4.tsx b/examples/static-map/src/static-map-4.tsx new file mode 100644 index 00000000..eab29237 --- /dev/null +++ b/examples/static-map/src/static-map-4.tsx @@ -0,0 +1,45 @@ +import React from 'react'; +import {StaticMap, createStaticMapsUrl} from '@vis.gl/react-google-maps'; + +const API_KEY = + globalThis.GOOGLE_MAPS_API_KEY ?? (process.env.GOOGLE_MAPS_API_KEY as string); + +export default function StaticMap4() { + const staticMapsUrl = createStaticMapsUrl({ + apiKey: API_KEY, + scale: 2, + width: 600, + height: 600, + paths: [ + { + color: '0xff00ff', + fillcolor: '0xffff00', + coordinates: + 'enc:}zswFtikbMjJzZ|RdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A|PfYlvApz@bl@tcAdTpGpVwQtX}i@|Gen@lCeAda@bjA`q@v}@rfAbjA|EwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ|[uPzNtA`LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG`]lL~MdTmEnCwJ[iJhOae@nCm[`Aq]qE_pAaNiyBuDurAuB}}Ay`@|EKv_@?|[qGji@lAhYyH`@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm|B~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa`Atf@uQj_Aee@pU_UrcA' + } + ], + style: [ + { + featureType: 'road.local', + elementType: 'geometry', + stylers: [{color: '#00ff00'}] + }, + { + featureType: 'landscape', + elementType: 'geometry.fill', + stylers: [{color: '#222222'}] + }, + { + elementType: 'labels', + stylers: [{invert_lightness: true}] + }, + { + featureType: 'road.arterial', + elementType: 'labels', + stylers: [{invert_lightness: false}] + } + ] + }); + + return ; +} diff --git a/examples/static-map/vite.config.js b/examples/static-map/vite.config.js new file mode 100644 index 00000000..522c6cb9 --- /dev/null +++ b/examples/static-map/vite.config.js @@ -0,0 +1,17 @@ +import {defineConfig, loadEnv} from 'vite'; + +export default defineConfig(({mode}) => { + const {GOOGLE_MAPS_API_KEY = ''} = loadEnv(mode, process.cwd(), ''); + + return { + define: { + 'process.env.GOOGLE_MAPS_API_KEY': JSON.stringify(GOOGLE_MAPS_API_KEY) + }, + resolve: { + alias: { + '@vis.gl/react-google-maps/examples.js': + 'https://visgl.github.io/react-google-maps/scripts/examples.js' + } + } + }; +}); diff --git a/package.json b/package.json index 9698d5f3..2ab1cde3 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,11 @@ "types": "./dist/index.d.ts", "default": "./dist/index.modern.mjs" }, + "./server": { + "require": "./dist/server/index.umd.js", + "types": "./dist/server/index.d.ts", + "default": "./dist/server/index.modern.mjs" + }, "./examples.css": "./dist/examples.css" }, "types": "dist/index.d.ts", @@ -25,10 +30,11 @@ "license": "MIT", "scripts": { "clean": "rm -rf ./dist && mkdir ./dist", - "build": "npm-run-all clean -p build:*", + "build": "npm-run-all clean -p build:**", "start": "run-p start:*", "build:examples": "cp ./examples/examples.css dist", "build:microbundle": "microbundle -o dist/index.js -f modern,umd --globals react=React,react-dom=ReactDOM --jsx React.createElement --jsxFragment React.Fragment --no-compress --tsconfig tsconfig.build.json", + "build:microbundle:server": "microbundle -o dist/server/index.js -f modern,umd --globals react=React,react-dom=ReactDOM --jsx React.createElement --jsxFragment React.Fragment --no-compress --tsconfig tsconfig.build.json ./src/server/index.ts", "start:microbundle": "microbundle watch -o dist/index.js -f modern,umd --globals react=React,react-dom=ReactDOM --jsx React.createElement --jsxFragment React.Fragment --no-compress --tsconfig tsconfig.build.json", "test:linter": "eslint 'src/**/*.{ts,tsx}'", "test:tsc": "tsc --project tsconfig.test.json --noEmit", diff --git a/src/components/static-map.tsx b/src/components/static-map.tsx new file mode 100644 index 00000000..ae57d77d --- /dev/null +++ b/src/components/static-map.tsx @@ -0,0 +1,20 @@ +import React from 'react'; + +export {createStaticMapsUrl} from '../libraries/create-static-maps-url'; +export * from '../libraries/create-static-maps-url/types'; + +/** + * Props for the StaticMap component + */ +export type StaticMapProps = { + url: string; + className?: string; +}; + +export const StaticMap = (props: StaticMapProps) => { + const {url, className} = props; + + if (!url) throw new Error('URL is required'); + + return ; +}; diff --git a/src/index.ts b/src/index.ts index 08514a57..2463f303 100644 --- a/src/index.ts +++ b/src/index.ts @@ -4,6 +4,7 @@ export * from './components/advanced-marker'; export * from './components/api-provider'; export * from './components/info-window'; export * from './components/map'; +export * from './components/static-map'; export * from './components/map-control'; export * from './components/marker'; export * from './components/pin'; diff --git a/src/libraries/__tests__/create-static-maps-url.test.ts b/src/libraries/__tests__/create-static-maps-url.test.ts new file mode 100644 index 00000000..eb61c64f --- /dev/null +++ b/src/libraries/__tests__/create-static-maps-url.test.ts @@ -0,0 +1,233 @@ +import {initialize} from '@googlemaps/jest-mocks'; + +import {createStaticMapsUrl} from '../create-static-maps-url'; + +const requiredParams = { + apiKey: 'test-api-key', + width: 600, + height: 400 +}; + +beforeEach(() => { + initialize(); +}); + +describe('createStaticMapsUrl', () => { + const API_KEY = 'test-api-key'; + + test('creates basic URL with required parameters', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + zoom: 12 + }); + expect(url).toMatch( + /^https:\/\/maps\.googleapis\.com\/maps\/api\/staticmap/ + ); + expect(url).toContain('center=40.714728%2C-73.998672'); + expect(url).toContain('zoom=12'); + expect(url).toContain('size=600x400'); + expect(url).toContain(`key=${API_KEY}`); + }); + + test('includes map type', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + zoom: 12, + mapType: google.maps.MapTypeId.SATELLITE + }); + expect(url).toContain('maptype=satellite'); + }); + + test('handles single marker', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + markers: [{location: {lat: 40.714728, lng: -73.998672}}] + }); + + const markerParam = encodeURIComponent('40.714728,-73.998672'); + + expect(url).toContain(`markers=${markerParam}`); + }); + + test('handles multiple markers with same style', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + markers: [ + {location: {lat: 40.714728, lng: -73.998672}, color: 'blue'}, + {location: {lat: 41.715728, lng: -72.999672}, color: 'blue'} + ] + }); + + const markerParam = encodeURIComponent( + `color:blue|40.714728,-73.998672|41.715728,-72.999672` + ); + + expect(url).toContain(`markers=${markerParam}`); + }); + + test('handles multiple markers with different style', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + markers: [ + {location: {lat: 40.714728, lng: -73.998672}, color: 'blue'}, + {location: {lat: 41.715728, lng: -72.999672}, color: 'red'} + ] + }); + const blueMarkerParam = encodeURIComponent( + `color:blue|40.714728,-73.998672` + ); + const redMarkerParam = encodeURIComponent(`color:red|41.715728,-72.999672`); + + expect(url).toContain(`markers=${blueMarkerParam}`); + expect(url).toContain(`markers=${redMarkerParam}`); + }); + + test('includes custom marker styles', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + markers: [ + { + location: {lat: 40.714728, lng: -73.998672}, + color: 'red', + label: 'A', + size: 'mid' + } + ] + }); + const markerParam = encodeURIComponent( + 'color:red|label:A|size:mid|40.714728,-73.998672' + ); + + expect(url).toContain(`markers=${markerParam}`); + }); + + test('includes scale parameter', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + scale: 2 + }); + expect(url).toContain('scale=2'); + }); + + test('includes format parameter', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + format: 'png32' + }); + expect(url).toContain('format=png32'); + }); + + test('includes language parameter', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + language: 'de' + }); + + expect(url).toContain(`language=de`); + }); + + test('includes region parameter', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + region: 'en' + }); + + expect(url).toContain(`region=en`); + }); + + test('includes map_id parameter', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + mapId: '8e0a97af9386fef' + }); + const encodedMapId = encodeURIComponent('8e0a97af9386fef'); + expect(url).toContain(`map_id=${encodedMapId}`); + }); + + test('handles single path', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + paths: [ + { + coordinates: [ + {lat: 40.737102, lng: -73.990318}, + {lat: 40.749825, lng: -73.987963} + ], + color: 'blue', + weight: 5 + } + ] + }); + const encodedPath = encodeURIComponent( + 'color:blue|weight:5|40.737102,-73.990318|40.749825,-73.987963' + ); + expect(url).toContain(`path=${encodedPath}`); + }); + + test('handles multiple paths with different styles', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + paths: [ + { + coordinates: [{lat: 40.737102, lng: -73.990318}, 'Hamburg, Germany'], + color: 'blue', + weight: 5 + }, + { + coordinates: [ + {lat: 40.737102, lng: -73.990318}, + {lat: 40.736102, lng: -73.989318} + ], + color: 'red', + weight: 2 + } + ] + }); + const encodedPath1 = encodeURIComponent( + 'color:blue|weight:5|40.737102,-73.990318|Hamburg, Germany' + ).replace(/%20/g, '+'); + const encodedPath2 = encodeURIComponent( + 'color:red|weight:2|40.737102,-73.990318|40.736102,-73.989318' + ); + expect(url).toContain(`path=${encodedPath1}`); + expect(url).toContain(`path=${encodedPath2}`); + }); + + test('includes style parameters', () => { + const url = createStaticMapsUrl({ + ...requiredParams, + center: {lat: 40.714728, lng: -73.998672}, + style: [ + { + featureType: 'road', + elementType: 'geometry', + stylers: [{color: '#00ff00'}] + }, + { + featureType: 'water', + elementType: 'geometry', + stylers: [{color: '#0000ff'}] + } + ] + }); + + const style1 = encodeURIComponent( + 'feature:road|element:geometry|color:0x00ff00' + ); + const style2 = encodeURIComponent( + 'feature:water|element:geometry|color:0x0000ff' + ); + expect(url).toContain(`style=${style1}`); + expect(url).toContain(`style=${style2}`); + }); +}); diff --git a/src/libraries/create-static-maps-url/assemble-map-type-styles.ts b/src/libraries/create-static-maps-url/assemble-map-type-styles.ts new file mode 100644 index 00000000..e997a228 --- /dev/null +++ b/src/libraries/create-static-maps-url/assemble-map-type-styles.ts @@ -0,0 +1,52 @@ +import {formatParam} from './helpers'; + +/** + * Converts an array of Google Maps style objects into an array of style strings + * compatible with the Google Static Maps API. + * + * @param styles - An array of Google Maps MapTypeStyle objects that define the styling rules + * @returns An array of formatted style strings ready to be used with the Static Maps API + * + * @example + * const styles = [{ + * featureType: "road", + * elementType: "geometry", + * stylers: [{color: "#ff0000"}, {weight: 1}] + * }]; + * + * const styleStrings = assembleMapTypeStyles(styles); + * // Returns: ["|feature:road|element:geometry|color:0xff0000|weight:1"] + * + * Each style string follows the format: + * "feature:{featureType}|element:{elementType}|{stylerName}:{stylerValue}" + * + * Note: Color values with hexadecimal notation (#) are automatically converted + * to the required 0x format for the Static Maps API. + */ +export function assembleMapTypeStyles( + styles: Array +): string[] { + return styles + .map((mapTypeStyle: google.maps.MapTypeStyle) => { + const {featureType, elementType, stylers = []} = mapTypeStyle; + + let styleString = ''; + + if (featureType) { + styleString += `|feature:${featureType}`; + } + + if (elementType) { + styleString += `|element:${elementType}`; + } + + for (const styler of stylers) { + Object.entries(styler).forEach(([name, value]) => { + styleString += `|${name}:${String(value).replace('#', '0x')}`; + }); + } + + return styleString; + }) + .map(formatParam); +} diff --git a/src/libraries/create-static-maps-url/assemble-marker-params.ts b/src/libraries/create-static-maps-url/assemble-marker-params.ts new file mode 100644 index 00000000..3498afbc --- /dev/null +++ b/src/libraries/create-static-maps-url/assemble-marker-params.ts @@ -0,0 +1,79 @@ +import {formatParam} from './helpers'; +import {StaticMapsMarker} from './types'; + +/** + * Assembles marker parameters for static maps. + * + * This function takes an array of markers and groups them by their style properties. + * It then creates a string representation of these markers, including their styles and locations, + * which can be used as parameters for static map APIs. + * + * @param {StaticMapsMarker[]} [markers=[]] - An array of markers to be processed. Each marker can have properties such as color, label, size, scale, icon, anchor, and location. + * @returns {string[]} An array of strings, each representing a group of markers with their styles and locations. + * + * @example + * const markers = [ + * { color: 'blue', label: 'A', size: 'mid', location: '40.714728,-73.998672' }, + * { color: 'blue', label: 'B', size: 'mid', location: '40.714728,-73.998672' }, + * { icon: 'http://example.com/icon.png', location: { lat: 40.714728, lng: -73.998672 } } + * ]; + * const params = assembleMarkerParams(markers); + * // Params will be an array of strings representing the marker parameters + * Example output: [ + * "color:blue|label:A|size:mid|40.714728,-73.998672|40.714728,-73.998672", + * "color:blue|label:B|size:mid|40.714728,-73.998672|40.714728,-73.998672", + * "icon:http://example.com/icon.png|40.714728,-73.998672" + * ] + */ +export function assembleMarkerParams(markers: StaticMapsMarker[] = []) { + const markerParams: Array = []; + + // Group markers by style + const markersByStyle = markers?.reduce( + (styles, marker) => { + const {color = 'red', label, size, scale, icon, anchor} = marker; + + // Create a unique style key based on either icon properties or standard marker properties + const relevantProps = icon ? [icon, anchor, scale] : [color, label, size]; + const key = relevantProps.filter(Boolean).join('-'); + + styles[key] = styles[key] || []; + styles[key].push(marker); + return styles; + }, + {} as Record + ); + + Object.values(markersByStyle ?? {}).forEach(markers => { + let markerParam: string = ''; + + const {icon} = markers[0]; + + // Create marker style from first marker in group since all markers share the same style. + Object.entries(markers[0]).forEach(([key, value]) => { + // Determine which properties to include based on whether marker uses custom icon + const relevantKeys = icon + ? ['icon', 'anchor', 'scale'] + : ['color', 'label', 'size']; + + if (relevantKeys.includes(key)) { + markerParam += `|${key}:${value}`; + } + }); + + // Add location coordinates for each marker in the style group + // Handles both string locations and lat/lng object formats. + for (const marker of markers) { + const location = + typeof marker.location === 'string' + ? marker.location + : `${marker.location.lat},${marker.location.lng}`; + + markerParam += `|${location}`; + } + + markerParams.push(markerParam); + }); + + return markerParams.map(formatParam); +} diff --git a/src/libraries/create-static-maps-url/assemble-path-params.ts b/src/libraries/create-static-maps-url/assemble-path-params.ts new file mode 100644 index 00000000..a24c5fed --- /dev/null +++ b/src/libraries/create-static-maps-url/assemble-path-params.ts @@ -0,0 +1,79 @@ +import {formatLocation, formatParam} from './helpers'; +import {StaticMapsPath} from './types'; + +/** + * Assembles path parameters for the Static Maps Api from an array of paths. + * + * This function groups paths by their style properties (color, weight, fillcolor, geodesic) + * and then constructs a string of path parameters for each group. Each path parameter string + * includes the style properties and the coordinates of the paths. + * + * @param {Array} [paths=[]] - An array of paths to be assembled into path parameters. + * @returns {Array} An array of path parameter strings. + * + * @example + * const paths = [ + * { + * color: 'red', + * weight: 5, + * coordinates: [ + * { lat: 40.714728, lng: -73.998672 }, + * { lat: 40.718217, lng: -73.998284 } + * ] + * } + * ]; + * + * const pathParams = assemblePathParams(paths); + * Output: [ + * 'color:red|weight:5|40.714728,-73.998672|40.718217,-73.998284' + * ] + */ +export function assemblePathParams(paths: Array = []) { + const pathParams: Array = []; + + // Group paths by their style properties (color, weight, fillcolor, geodesic) + // to combine paths with identical styles into single parameter strings + const pathsByStyle = paths?.reduce( + (styles, path) => { + const {color = 'default', weight, fillcolor, geodesic} = path; + + // Create unique key for this style combination + const key = [color, weight, fillcolor, geodesic] + .filter(Boolean) + .join('-'); + + styles[key] = styles[key] || []; + styles[key].push(path); + return styles; + }, + {} as Record> + ); + + // Process each group of paths with identical styles + Object.values(pathsByStyle ?? {}).forEach(paths => { + let pathParam = ''; + + // Build style parameter string using properties from first path in group + // since all paths in this group share the same style + Object.entries(paths[0]).forEach(([key, value]) => { + if (['color', 'weight', 'fillcolor', 'geodesic'].includes(key)) { + pathParam += `|${key}:${value}`; + } + }); + + // Add location for all marker in style group + for (const path of paths) { + if (typeof path.coordinates === 'string') { + pathParam += `|${decodeURIComponent(path.coordinates)}`; + } else { + for (const location of path.coordinates) { + pathParam += `|${formatLocation(location)}`; + } + } + } + + pathParams.push(pathParam); + }); + + return pathParams.map(formatParam); +} diff --git a/src/libraries/create-static-maps-url/helpers.ts b/src/libraries/create-static-maps-url/helpers.ts new file mode 100644 index 00000000..192f1667 --- /dev/null +++ b/src/libraries/create-static-maps-url/helpers.ts @@ -0,0 +1,26 @@ +import {StaticMapsLocation} from './types'; + +/** + * Formats a location into a string representation suitable for Google Static Maps API. + * + * @param location - The location to format, can be either a string or an object with lat/lng properties + * @returns A string representation of the location in the format "lat,lng" or the original string + * + * @example + * // Returns "40.714728,-73.998672" + * formatLocation({ lat: 40.714728, lng: -73.998672 }) + * + * @example + * // Returns "New York, NY" + * formatLocation("New York, NY") + */ +export function formatLocation(location: StaticMapsLocation): string { + return typeof location === 'string' + ? location + : `${location.lat},${location.lng}`; +} + +// Used for removing the leading pipe from the param string +export function formatParam(string: string) { + return string.slice(1); +} diff --git a/src/libraries/create-static-maps-url/index.ts b/src/libraries/create-static-maps-url/index.ts new file mode 100644 index 00000000..e18205da --- /dev/null +++ b/src/libraries/create-static-maps-url/index.ts @@ -0,0 +1,141 @@ +import {assembleMarkerParams} from './assemble-marker-params'; +import {assemblePathParams} from './assemble-path-params'; +import {formatLocation} from './helpers'; + +import {StaticMapsApiOptions} from './types'; +import {assembleMapTypeStyles} from './assemble-map-type-styles'; + +const STATIC_MAPS_BASE = 'https://maps.googleapis.com/maps/api/staticmap'; + +/** + * Creates a URL for the Google Static Maps API with the specified parameters. + * + * @param {Object} options - The configuration options for the static map + * @param {string} options.apiKey - Your Google Maps API key (required) + * @param {number} options.width - The width of the map image in pixels (required) + * @param {number} options.height - The height of the map image in pixels (required) + * @param {StaticMapsLocation} [options.center] - The center point of the map (lat/lng or address). + * Required if no markers or paths or "visible locations" are provided. + * @param {number} [options.zoom] - The zoom level of the map. Required if no markers or paths or "visible locations" are provided. + * @param {1|2|4} [options.scale] - The resolution of the map (1, 2, or 4) + * @param {string} [options.format] - The image format (png, png8, png32, gif, jpg, jpg-baseline) + * @param {string} [options.mapType] - The type of map (roadmap, satellite, terrain, hybrid) + * @param {string} [options.language] - The language of the map labels + * @param {string} [options.region] - The region code for the map + * @param {string} [options.map_id] - The Cloud-based map style ID + * @param {StaticMapsMarker[]} [options.markers=[]] - Array of markers to display on the map + * @param {StaticMapsPath[]} [options.paths=[]] - Array of paths to display on the map + * @param {StaticMapsLocation[]} [options.visible=[]] - Array of locations that should be visible on the map + * @param {MapTypeStyle[]} [options.style=[]] - Array of style objects to customize the map appearance + * + * @returns {string} The complete Google Static Maps API URL + * + * @throws {Error} If API key is not provided + * @throws {Error} If width or height is not provided + * + * @example + * const url = createStaticMapsUrl({ + * apiKey: 'YOUR_API_KEY', + * width: 600, + * height: 400, + * center: { lat: 40.714728, lng: -73.998672 }, + * zoom: 12, + * markers: [ + * { + * location: { lat: 40.714728, lng: -73.998672 }, + * color: 'red', + * label: 'A' + * } + * ], + * paths: [ + * { + * coordinates: [ + * { lat: 40.714728, lng: -73.998672 }, + * { lat: 40.719728, lng: -73.991672 } + * ], + * color: '0x0000ff', + * weight: 5 + * } + * ], + * style: [ + * { + * featureType: 'road', + * elementType: 'geometry', + * stylers: [{color: '#00ff00'}] + * } + * ] + * }); + * + * // Results in URL similar to: + * // https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY + * // &size=600x400 + * // ¢er=40.714728,-73.998672&zoom=12 + * // &markers=color:red|label:A|40.714728,-73.998672 + * // &path=color:0x0000ff|weight:5|40.714728,-73.998672|40.719728,-73.991672 + * // &style=feature:road|element:geometry|color:0x00ff00 + */ +export function createStaticMapsUrl({ + apiKey, + width, + height, + center, + zoom, + scale, + format, + mapType, + language, + region, + mapId, + markers = [], + paths = [], + visible = [], + style = [] +}: StaticMapsApiOptions) { + if (!apiKey) throw new Error('API key is required'); + if (!width || !height) throw new Error('Width and height are required'); + + const params: Record = { + key: apiKey, + size: `${width}x${height}`, + ...(center && {center: formatLocation(center)}), + ...(zoom && {zoom}), + ...(scale && {scale}), + ...(format && {format}), + ...(mapType && {maptype: mapType}), + ...(language && {language}), + ...(region && {region}), + ...(mapId && {map_id: mapId}) + }; + + const url = new URL(STATIC_MAPS_BASE); + + // Params that don't need special handling + Object.entries(params).forEach(([key, value]) => { + url.searchParams.append(key, String(value)); + }); + + // Assemble Markers + for (const markerParam of assembleMarkerParams(markers)) { + url.searchParams.append('markers', markerParam); + } + + // Assemble Paths + for (const pathParam of assemblePathParams(paths)) { + url.searchParams.append('path', pathParam); + } + + // Assemble visible locations + if (visible.length) { + url.searchParams.append( + 'visible', + visible.map(location => formatLocation(location)).join('|') + ); + } + + // Assemble Map Type Styles + for (const styleString of assembleMapTypeStyles(style)) { + url.searchParams.append('style', styleString); + } + + return url.toString(); +} diff --git a/src/libraries/create-static-maps-url/types.ts b/src/libraries/create-static-maps-url/types.ts new file mode 100644 index 00000000..1cc056cf --- /dev/null +++ b/src/libraries/create-static-maps-url/types.ts @@ -0,0 +1,37 @@ +export type StaticMapsLocation = google.maps.LatLngLiteral | string; + +export type StaticMapsMarker = { + location: StaticMapsLocation; + color?: string; + size?: 'tiny' | 'mid' | 'small'; + label?: string; + icon?: string; + anchor?: string; + scale?: 1 | 2 | 4; +}; + +export type StaticMapsPath = { + coordinates: Array | string; + weight?: number; + color?: string; + fillcolor?: string; + geodesic?: boolean; +}; + +export type StaticMapsApiOptions = { + apiKey: string; + width: number; + height: number; + center?: StaticMapsLocation; + zoom?: number; + scale?: number; + format?: 'png' | 'png8' | 'png32' | 'gif' | 'jpg' | 'jpg-baseline'; + mapType?: google.maps.MapTypeId; + language?: string; + region?: string; + mapId?: string; + markers?: Array; + paths?: Array; + visible?: Array; + style?: google.maps.MapTypeStyle[]; +}; diff --git a/src/server/index.ts b/src/server/index.ts new file mode 100644 index 00000000..7a152d94 --- /dev/null +++ b/src/server/index.ts @@ -0,0 +1,3 @@ +/// + +export * from '../components/static-map'; diff --git a/website/src/examples-sidebar.js b/website/src/examples-sidebar.js index 688283a7..a25f9899 100644 --- a/website/src/examples-sidebar.js +++ b/website/src/examples-sidebar.js @@ -26,7 +26,8 @@ const sidebars = { 'directions', 'deckgl-overlay', 'map-3d', - 'extended-component-library' + 'extended-component-library', + 'static-map' ] } ] diff --git a/website/src/examples/static-map.mdx b/website/src/examples/static-map.mdx new file mode 100644 index 00000000..91daf33a --- /dev/null +++ b/website/src/examples/static-map.mdx @@ -0,0 +1,5 @@ +# Static Map + +import App from 'website-examples/static-map/src/app'; + + diff --git a/website/static/images/examples/static-map.jpg b/website/static/images/examples/static-map.jpg new file mode 100644 index 00000000..603abc69 Binary files /dev/null and b/website/static/images/examples/static-map.jpg differ