fix(playground): implement new design, info overlay, example name to …

…url (#11) * fix(playground): implement new design, info overlay, example name to url * fix(playground): use short license header As described [here][google-oss-licenses], we can use the short license header for our examples instead of the full-blown Apache header. [google-oss-licenses]: https://opensource.google/documentation/reference/releasing/preparing#license-headers * fix: add infowindow text * chore: revert accidental change to license header * docs: update links in readme --------- Co-authored-by: Martin Schuhfuss <[email protected]>
googlemaps · Aug 30, 2023 · 0b90d88 · 0b90d88
1 parent bd2e73f
commit 0b90d88
Show file tree

Hide file tree

Showing 29 changed files with 577 additions and 361 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,22 @@
 # Advanced Markers Utility Library
 
-The `@googlemaps/adv-markers-utils` package is a library to simplify common patterns for using [Advanced Markers](https://developers.google.com/maps/documentation/javascript/advanced-markers/overview) in the Maps JavaScript API.
+The `@googlemaps/adv-markers-utils` package is a library to simplify common
+patterns for using [Advanced Markers][gmp-adv-markers-overview] in the Maps
+JavaScript API.
 
 It combines all features from the `google.maps.marker.AdvancedMarkerElement` and
 `google.maps.marker.PinElement` classes into a single interface and adds some
 useful features like automatic color selection, handling for icon-fonts, and
 automatic handling of small to medium datasets.
 
+To see some examples of what it can do, head over to our [marker playground][playground]
+and test it for yourself.
+
+[gmp-adv-markers-overview]: https://developers.google.com/maps/documentation/javascript/advanced-markers/overview
+[playground]: https://googlemaps.github.io/js-adv-markers-utils/playground/
+
 ## Installation
+
 If you're using a bundler (like webpack, rollup, vite, etc.) for your project,
 you can install the package using npm or yarn:
 
@@ -23,9 +32,9 @@ import {Marker} from '@googlemaps/adv-markers-utils';
 const domElement = document.querySelector('#map');
 
 async function main() {
-  // load Google Maps API
+  // load Google Maps API and it's Marker library
   // (see https://developers.google.com/maps/documentation/javascript/dynamic-loading)
-  const {Map} = await google.maps.importLibrary('maps') as google.maps.MapsLibrary;
+  const {Map} = await google.maps.importLibrary('maps');
   await google.maps.importLibrary('marker');
 
   // create the map
@@ -40,11 +49,14 @@ async function main() {
 main();
 ```
 
+We also support usage with native ESM and UMD, [see the examples here](./examples/html)
+for more information.
+
 ## API Documentation
 
 The API documentation generated by typedoc is available here:
 
-[API Documentation](https://googlemaps.github.io/adv-markers-utils/)
+[API Documentation](https://googlemaps.github.io/js-adv-markers-utils/)
 
 ## Core Concepts
 

diff --git a/examples/playground/index.html b/examples/playground/index.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <!--
  Copyright 2023 Google LLC
 
@@ -22,94 +22,109 @@
       name="viewport"
       content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
     />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link
       rel="stylesheet"
-      href="https://ui-components.ubilabs.com/css/v1/ubilabs-styles.css"
+      href="https://fonts.googleapis.com/css?family=Google+Sans:400,500,700|Roboto+Mono:400,500,700&display=block"
     />
-    <style>
-      html,
-      body {
-        width: 100%;
-        height: 100%;
-        margin: 0;
-        display: flex;
-        flex-flow: row nowrap;
-      }
+    <link rel="stylesheet" href="styles.css" />
 
-      #map {
-        height: 100%;
-        width: 100%;
-        flex: 1 1 auto;
-      }
-
-      .sidebar {
-        width: 100%;
-        min-width: 480px;
-        flex: 1 1 auto;
-        display: flex;
-        flex-flow: column nowrap;
-      }
-
-      .header {
-        font-size: 24px;
-        padding: 1rem;
-        display: flex;
-        flex-flow: row nowrap;
-        justify-content: space-between;
-        align-items: center;
-      }
-
-      .controls {
-        display: flex;
-        gap: 8px;
-      }
-
-      .controls select {
-        border: 1px solid rgba(0, 0, 0, 0.4);
-      }
-
-      h1 {
-        font-size: 1em;
-        margin: 0;
-        font-weight: normal;
-        display: inline-block;
-      }
-
-      #editor {
-        height: 100%;
-        flex: 1 1 auto;
-      }
-
-      .links {
-        padding: 1rem;
-      }
-
-      .links ul {
-        list-style-type: none;
-        margin: 0;
-        padding: 0;
-      }
-
-      .links li {
-        display: inline-block;
-      }
-    </style>
-    <title>marker playground</title>
+    <title>Marker Playground</title>
   </head>
   <body>
     <div id="map"></div>
     <div class="sidebar">
       <div class="header">
-        <h1>marker playground</h1>
-        <div class="controls">
-          <select id="example-select"></select>
-          <button id="btn-compile-and-run" title="Run the code (⌘ + ⏎)">
-            Run ▶
+        <img src="/gmp-icon.svg" alt="Google Maps Platform" />
+
+        <div class="info-container">
+          <h1>Marker Playground</h1>
+          <button id="show-dialog-button">
+            <span class="info-icon"></span>
           </button>
         </div>
       </div>
+      <div class="controls">
+        <select id="example-select"></select>
+      </div>
       <div id="editor"></div>
+      <div class="footer">
+        <button id="btn-compile-and-run" title="Run the code (⌘ + ⏎)">
+          Run <span class="chevron-right"></span>
+        </button>
+      </div>
     </div>
+    <dialog id="info-dialog">
+      <form>
+        <div class="dialog-header">
+          <h3>Google Maps Advanced Markers Utils</h3>
+          <button
+            class="close-dialog-button"
+            value="cancel"
+            formmethod="dialog"
+          >
+            <span class="close-icon"></span>
+          </button>
+        </div>
+        <div class="dialog-main">
+          <h2>Marker Playground</h2>
+          <p>
+            This application allows you to explore the examples and the API
+            provided by the <code>@googlemaps/adv-markers-utils</code> without
+            having to set up your own website and API key for that. The editor
+            provides full TypeScript code assistance for the Google Maps API as
+            well as the <code>@googlemaps/adv-markers-utils</code> module.
+          </p>
+          <div class="accordion">
+            <details>
+              <summary>Writing and contributing examples</summary>
+              <p>
+                Each example is a single typescript file with a function as it's
+                default export. When the example is run, that function will be
+                called with the <code>google.maps.Map</code> instance as
+                argument. If any permanent changes are done to the environment
+                (browser event handlers or timers for example), the function has
+                to return a cleanup-function that reverts the changes made to
+                the environment.
+              </p>
+              <p>
+                Examples should generally focus on demonstrating a single
+                feature of the
+                <code>@googlemaps/adv-markers-utils</code> package or a unique
+                way to use the features to solve a real-world problem in a
+                simplified way. If you notice features not covered by examples
+                or if you have a good idea for an example, feel free to
+                <a
+                  href="https://github.com/googlemaps/js-adv-markers-utils/issues/new"
+                  target="_blank"
+                  >create a feature-request</a
+                >
+                or send us a pull-request for a new file in the
+                <a
+                  href="https://github.com/googlemaps/js-adv-markers-utils/tree/main/examples/playground/src/code-samples"
+                  >examples directory</a
+                >.
+              </p>
+            </details>
+          </div>
+        </div>
+        <div class="dialog-footer">
+          <a
+            href="https://github.com/googlemaps/js-adv-markers-utils/"
+            target="_blank"
+            rel="noopener noreferrer"
+            >Github</a
+          >
+          <a
+            href="https://googlemaps.github.io/adv-markers-utils/"
+            target="_blank"
+            rel="noopener noreferrer"
+            >Documentation</a
+          >
+        </div>
+      </form>
+    </dialog>
 
     <script type="module" src="./src/main.ts"></script>
   </body>

diff --git a/examples/playground/public/accordion-arrow.svg b/examples/playground/public/accordion-arrow.svg
diff --git a/examples/playground/public/arrow-dropdown.svg b/examples/playground/public/arrow-dropdown.svg
diff --git a/examples/playground/public/chevron-right.svg b/examples/playground/public/chevron-right.svg
diff --git a/examples/playground/public/close-icon.svg b/examples/playground/public/close-icon.svg
diff --git a/examples/playground/public/gmp-icon.svg b/examples/playground/public/gmp-icon.svg
diff --git a/examples/playground/public/info-icon.svg b/examples/playground/public/info-icon.svg
diff --git a/examples/playground/public/link-icon.svg b/examples/playground/public/link-icon.svg
diff --git a/examples/playground/src/code-samples/00.default.ts b/examples/playground/src/code-samples/00.default.ts
@@ -1,18 +1,5 @@
-/*
- * Copyright 2023 Google LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// Copyright 2023 Google LLC.
+// SPDX-License-Identifier: Apache-2.0
 
 //
 // Marker-API Example Playground

diff --git a/examples/playground/src/code-samples/01.simple-marker.ts b/examples/playground/src/code-samples/01.simple-marker.ts
@@ -1,18 +1,5 @@
-/**
- * Copyright 2023 Google LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// Copyright 2023 Google LLC.
+// SPDX-License-Identifier: Apache-2.0
 
 // title: create marker and add it to the map
 import {Marker} from '@googlemaps/adv-markers-utils';

diff --git a/examples/playground/src/code-samples/02.update-position.ts b/examples/playground/src/code-samples/02.update-position.ts
@@ -1,18 +1,5 @@
-/**
- * Copyright 2023 Google LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// Copyright 2023 Google LLC.
+// SPDX-License-Identifier: Apache-2.0
 
 // title: specifying and updating position
 import {Marker} from '@googlemaps/adv-markers-utils';

diff --git a/examples/playground/src/code-samples/03.pin-styling.ts b/examples/playground/src/code-samples/03.pin-styling.ts
@@ -1,18 +1,5 @@
-/**
- * Copyright 2023 Google LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// Copyright 2023 Google LLC.
+// SPDX-License-Identifier: Apache-2.0
 
 // title: simple marker customizations: color
 

diff --git a/examples/playground/src/code-samples/04.pin-icons.ts b/examples/playground/src/code-samples/04.pin-icons.ts
@@ -1,18 +1,5 @@
-/**
- * Copyright 2023 Google LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// Copyright 2023 Google LLC.
+// SPDX-License-Identifier: Apache-2.0
 
 // title: simple marker customizations: icons
 import {Marker} from '@googlemaps/adv-markers-utils';

diff --git a/examples/playground/src/code-samples/04b.places-icons.ts b/examples/playground/src/code-samples/04b.places-icons.ts
@@ -1,18 +1,5 @@
-/**
- * Copyright 2023 Google LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// Copyright 2023 Google LLC.
+// SPDX-License-Identifier: Apache-2.0
 
 // title: simple marker customizations: Google Maps Places API icons