feat: improved playground module-loading (#21)

* feat: improved playground module-loading

The playground now uses the same package-name and imports as would be used in external projects. Resolving the modules for running is no longer hardcoded.

* fix: disable watch-mode for library

Running microbundle in watch-mode causes problems with files missing on reload, which is rather annoying.

* fix: load examples via vite-globs instead of custom script

* fix: add code-samples to dropdown menu

examples/playground/README.md

@@ -5,21 +5,21 @@ the marker API.
 
 ## Get Started
 
-1.  Install dependencies:
+1. Install dependencies:
 
-    npm install
+   npm install
 
-2.  create the `.env` file. The API Key to use
-    [can be found here][gcloud_console_maps_credentials].
+2. create the `.env` file. The API Key to use
+   [can be found here][gcloud_console_maps_credentials].
 
-        GOOGLE_MAPS_API_KEY="<INSERT API KEY HERE>"
-        PRODUCTION_BASEURL="/marker-api-playground/"
+       GOOGLE_MAPS_API_KEY="<INSERT API KEY HERE>"
+       PRODUCTION_BASEURL="/marker-api-playground/"
 
-3.  start the 'playground' environment:
+3. start the 'playground' environment:
 
-    npm start
+   npm start
 
-4.  open http://localhost:5173 in your browser
+4. open http://localhost:5173 in your browser
 
 [gcloud_console_maps_credentials]: https://console.cloud.google.com/apis/credentials/key/cace4819-4b19-489c-bd49-d91300d72dab?project=ubilabs-dev
 
@@ -41,13 +41,13 @@ modules can only be imported using async imports from urls.
 - `/`: contains `index.html`, `examples.html` and configuration-files
 - `/scripts`: this is the place for utility scripts, mostly written in [zx][]
 - `/src`: the typescript source-root. The application entrypoint is in `main.ts`
-- `/src/code-samples`: contains the source-files for all examples. The 
+- `/src/code-samples`: contains the source-files for all examples. The
   typescript files here should all follow the conventions for examples below.
-  For the examples index-page, these files are packaged into examples.json 
+  For the examples index-page, these files are packaged into examples.json
   by the `build:examples` npm task (see
   `/scripts/update-examples.mjs`)
-- `/src/code-samples/lib`: contains the typescript declaration-files 
-  generated from the library that are required by the editor and referenced 
+- `/src/code-samples/lib`: contains the typescript declaration-files
+  generated from the library that are required by the editor and referenced
   by the examples. Those files are generated by `npm run build:dts` from the
   library files.
 - `/types` is for additional typescript declarations
@@ -64,16 +64,15 @@ modules can only be imported using async imports from urls.
 - the first line of the example has to contain a comment in the form:
   `// title: This describes what it does` - this comment will be the text
   shown in the example-index
-- the example must import the marker-library via the `*.d.ts` files
-  available in `./src/code-samples/lib/`
-  (e.g. `import {Marker} from './lib/marker';`).
+- the example must import components from the marker-library using regular
+  imports (e.g. `import {Marker} from '@ubilabs/google-maps-marker';`).
 - there has to be a default export, which will be called with the
   map-instance as parameter when the script is run
 - When any changes are done in the browser environment (event-listeners,
   timeouts, intervals, ...), the exported function has to return a cleanup
-  function removing all those. This doesn't apply for created markers, those
-  are automatically removed from the map when a new version of the script is
-  executed.
+  function removing all those. This doesn't apply for created markers and
+  marker-collections, those are automatically removed from the map when a
+  new version of the script is executed.
 
 ## scripts, npm-tasks and deployment
 
@@ -88,8 +87,6 @@ The following supporting scripts and tasks are available:
 
 - `npm start`: starts the vite dev-server (this will also run the `build:dts`
   and `build:examples` tasks)
-- `npm run build:dts`: compiles all typescript-files in `./src/lib`
-  into corresponding declaration files in `./examples/lib`
 - `npm run build:examples`: runs the `script/update-examples.mjs` script to
   update the examples index in `./examples/examples.json`. The index is
   loaded in `examples.html` to render the list of examples

examples/playground/examples.html

@@ -19,6 +19,7 @@
         background: #1e1e1e;
         color: #d4d4d4;
       }
+
       main {
         max-width: 640px;
         width: 100%;
@@ -35,11 +36,21 @@ <h1>List of examples</h1>
     </main>
 
     <script type="module">
-      import data from './src/code-samples/examples.json';
       import {encode} from './src/snippet-encoder';
 
+      const files = import.meta.glob('./src/code-samples/*.ts', {
+        as: 'raw',
+        eager: true
+      });
+
       const root = document.querySelector('ul.examples');
-      for (const {title, source} of Object.values(data)) {
+      for (const [filename, source] of Object.entries(files)) {
+        const firstLine = source.slice(0, source.indexOf('\n')).trim();
+        let title = filename.replace(/^.*\//, '');
+        if (firstLine.startsWith('// title:')) {
+          title = firstLine.replace(/\/\/ title:\s*/, '');
+        }
+
         const el = document.createElement('li');
         const a = document.createElement('a');
 

examples/playground/index.html

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html>
+<html lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta
@@ -18,14 +18,14 @@
         margin: 0;
         display: flex;
         flex-flow: row nowrap;
-        background: #1e1e1e;
-        color: #d4d4d4;
       }
+
       #map {
         height: 100%;
         width: 100%;
         flex: 1 1 auto;
       }
+
       .sidebar {
         width: 100%;
         min-width: 480px;
@@ -43,6 +43,10 @@
         align-items: center;
       }
 
+      .controls {
+        display: flex;
+      }
+
       h1 {
         font-size: 1em;
         margin: 0;
@@ -58,24 +62,30 @@
       .links {
         padding: 1rem;
       }
+
       .links ul {
         list-style-type: none;
         margin: 0;
         padding: 0;
       }
+
       .links li {
         display: inline-block;
       }
     </style>
+    <title>marker playground</title>
   </head>
   <body>
     <div id="map"></div>
     <div class="sidebar">
       <div class="header">
-        <h1>Marker API Playground</h1>
-        <button id="btn-compile-and-run" title="Run the code (⌘ + ⏎)">
-          Run ▶
-        </button>
+        <h1>marker playground</h1>
+        <div class="controls">
+          <select id="example-select"></select>
+          <button id="btn-compile-and-run" title="Run the code (⌘ + ⏎)">
+            Run ▶
+          </button>
+        </div>
       </div>
       <div id="editor"></div>
       <div class="links">

examples/playground/package.json

@@ -1,13 +1,14 @@
 {
-  "name": "marker-api-design-testing-ground",
+  "name": "@ubilabs/google-maps-marker__playground",
   "version": "1.3.0",
   "scripts": {
-    "start": "run-p build:* && vite",
-    "build:dts": "tsc --declaration --emitDeclarationOnly --module esnext --target es2022 --lib es2022,dom --stripInternal --strict ../../src/*.ts --outDir ./src/code-samples/lib",
-    "build:examples": "zx ./scripts/update-examples.mjs",
+    "start": "npm-run-all -p build:* -s serve",
+    "build:lib": "cd ../.. && npm run build",
     "build": "run-p build:* && vite build",
     "preview": "run-s build && vite preview",
-    "deploy": "run-s build && gsutil -m rsync -drc ./dist/ gs://storage.ubidev.net/marker-api-playground/"
+    "deploy": "run-s build && gsutil -m rsync -drc ./dist/ gs://storage.ubidev.net/marker-api-playground/",
+    "serve": "vite",
+    "watch:library": "cd ../.. && npm run watch"
   },
   "keywords": [],
   "directories": {

examples/playground/src/code-samples/00.default.ts

@@ -8,8 +8,8 @@
 // <Cmd> + <S>        save the code to the URL
 //
 
-import {Marker} from './lib/marker';
-import {MaterialIcons} from './lib/icons';
+import {Marker} from '@ubilabs/google-maps-marker';
+import {MaterialIcons} from '@ubilabs/google-maps-marker/icons';
 
 export default (map: google.maps.Map) => {
   Marker.registerIconProvider(MaterialIcons());

examples/playground/src/code-samples/01.simple-marker.ts

@@ -1,12 +1,12 @@
 // title: create marker and add it to the map
-import {Marker} from './lib/marker';
+import {Marker} from '@ubilabs/google-maps-marker';
 
 export default (map: google.maps.Map) => {
   const m1 = new Marker();
   m1.position = {lat: 53.555, lng: 10.001};
   m1.map = map;
 
-  const m2 = new Marker({
+  new Marker({
     map,
     position: {lat: 53.55, lng: 10}
   });

examples/playground/src/code-samples/02.update-position.ts

@@ -1,5 +1,5 @@
 // title: specifying and updating position
-import {Marker} from './lib/marker';
+import {Marker} from '@ubilabs/google-maps-marker';
 
 export default (map: google.maps.Map) => {
   const m1 = new Marker({map});

examples/playground/src/code-samples/03.pin-styling.ts

@@ -1,5 +1,5 @@
 // title: simple marker customizations: color
-import {Marker} from './lib/marker';
+import {Marker} from '@ubilabs/google-maps-marker';
 
 export default (map: google.maps.Map) => {
   const m1 = new Marker({map, position: {lat: 50, lng: 10}});

examples/playground/src/code-samples/04.pin-icons.ts

@@ -1,6 +1,9 @@
 // title: simple marker customizations: icons
-import {Marker} from './lib/marker';
-import {MaterialIcons, MaterialIconsStyle} from './lib/icons';
+import {Marker} from '@ubilabs/google-maps-marker';
+import {
+  MaterialIcons,
+  MaterialIconsStyle
+} from '@ubilabs/google-maps-marker/icons';
 
 export default (map: google.maps.Map) => {
   // first we need to register the icon-provider, which is a function that knows how to create the kind of dom-element needed for an icon-set

examples/playground/src/code-samples/04b.places-icons.ts

@@ -1,7 +1,7 @@
 // title: simple marker customizations: Google Maps Places API icons
 
-import {Marker} from './lib/marker';
-import {PlaceIcons} from './lib/icons';
+import {Marker} from '@ubilabs/google-maps-marker';
+import {PlaceIcons} from '@ubilabs/google-maps-marker/icons';
 
 export default (map: google.maps.Map) => {
   Marker.registerIconProvider(PlaceIcons());

examples/playground/src/code-samples/05.hover-styling.ts

@@ -1,5 +1,5 @@
 // title: marker interactivity: hover
-import {Marker} from './lib/marker';
+import {Marker} from '@ubilabs/google-maps-marker';
 
 export default (map: google.maps.Map) => {
   const position = {lat: 53.5, lng: 10};

examples/playground/src/code-samples/06.click-events.ts

@@ -1,5 +1,5 @@
 // title: marker interactivity: click events
-import {Marker} from './lib/marker';
+import {Marker} from '@ubilabs/google-maps-marker';
 
 export default (map: google.maps.Map) => {
   const marker = new Marker({

examples/playground/src/code-samples/07.mulitple-marker-single-select.ts

@@ -1,5 +1,5 @@
 // title: multiple markers / single selection (w/ user-data)
-import {Marker} from './lib/marker';
+import {Marker} from '@ubilabs/google-maps-marker';
 
 function rnd(min: number, max: number) {
   return min + Math.random() * (max - min);
@@ -29,7 +29,7 @@ export default (map: google.maps.Map) => {
       {
         map,
         position,
-        color: ({data}) => (data.selected ? '#DB4437' : '#4285F4')
+        color: ({data}) => (data?.selected ? '#DB4437' : '#4285F4')
       },
       // initial user-data
       {selected: false}

examples/playground/src/code-samples/07b.mulitple-marker-single-select.ts

@@ -1,5 +1,5 @@
 // title: multiple markers / single selection (alternative w/ 'style objects')
-import {Attributes, Marker} from './lib/marker';
+import {Attributes, Marker} from '@ubilabs/google-maps-marker';
 
 function rnd(min: number, max: number) {
   return min + Math.random() * (max - min);

examples/playground/src/code-samples/08.attribute-dependencies.ts

@@ -1,6 +1,6 @@
 // title: dynamic attributes depending on each other
 
-import {Marker} from './lib/marker';
+import {Marker} from '@ubilabs/google-maps-marker';
 
 // dynamic attributes can be written to reliably depend on the current value
 // of another attribute, for example to make colors depend on the icon shown
@@ -14,7 +14,8 @@ export default (map: google.maps.Map) => {
   const marker = new Marker({
     position: {lat: 53.55, lng: 10.05},
     color: ({marker}) => (marker.hovered ? 'red' : 'green'),
-    borderColor: ({attr}) => (attr.color === 'red' ? 'black' : undefined),
-    map
+    borderColor: ({attr}) => (attr.color === 'red' ? 'black' : undefined)
   });
+
+  marker.map = map;
 };

examples/playground/src/code-samples/09.draggable-manual.ts

@@ -1,6 +1,6 @@
 // title: draggable markers / update position after drag
-import {Marker} from './lib/marker';
-import {MaterialIcons} from './lib/icons';
+import {Marker} from '@ubilabs/google-maps-marker';
+import {MaterialIcons} from '@ubilabs/google-maps-marker/icons';
 
 export default (map: google.maps.Map) => {
   Marker.registerIconProvider(MaterialIcons());
@@ -10,8 +10,8 @@ export default (map: google.maps.Map) => {
   m1.map = map;
 
   m1.draggable = true;
-  m1.addListener('dragend', ev => {
-    console.log('dragend', ev.latLng.toJSON());
-    m1.position = ev.latLng.toJSON();
+  m1.addListener('dragend', (ev: google.maps.MapMouseEvent) => {
+    console.log('dragend', ev.latLng?.toJSON());
+    m1.position = ev.latLng?.toJSON();
   });
 };