Add example page

.github/workflows/gh-pages.yml

@@ -0,0 +1,38 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3 #Setup Node
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: APIKEY=${{ secrets.APIKEY }} npm run build
+      - run: APIKEY=${{ secrets.APIKEY }} npm run examples
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./dist/example
+
+  deploy:
+    needs: build
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -6,7 +6,7 @@ Mappable JS API package
 
 [![npm version](https://badge.fury.io/js/%40mappable-world%2Fmappable-default-ui-theme.svg)](https://badge.fury.io/js/%40mappable-world%2Fmappable-default-ui-theme)
 [![npm](https://img.shields.io/npm/dm/@mappable-world/mappable-default-ui-theme.svg)](https://www.npmjs.com/package/@mappable-world/mappable-default-ui-theme)
-[![Build Status](https://github.com/mappable-world/@mappable-world/mappable-default-ui-theme/workflows/Run%20tests/badge.svg)](https://github.com/mappable-world/@mappable-world/mappable-default-ui-theme/actions/workflows/tests.yml)
+[![Build Status](https://github.com/mappable-world/mappable-default-ui-theme/workflows/Run%20tests/badge.svg)](https://github.com/mappable-world/@mappable-world/mappable-default-ui-theme/actions/workflows/tests.yml)
 
 ## How use
 
@@ -16,10 +16,10 @@ The package is located in the `dist` folder:
 - `dist/esm` es6 modules for direct connection in your project
 - `dist/index.js` Mappable JS Module
 
-Recommended use `MMapButtonExample` as usual npm package:
+Recommended use `@mappable-world/mappable-default-ui-theme` as usual npm package:
 
 ```sh
-npm i @mappable-world/mappable-default-ui-theme
+npm install @mappable-world/mappable-default-ui-theme
 ```
 
 and dynamic import
@@ -29,36 +29,33 @@ await mappable.ready;
 
 // ...
 
-const {MMapButtonExample} = await import('@mappable-world/mappable-default-ui-theme');
+const {MMapZoomControl} = await import('@mappable-world/mappable-default-ui-theme');
 
 // ...
 
-map.addChild(new MMapButtonExample(props));
+map.addChild(new MMapDefaultMarker(props));
 ```
 
 ### Usage without npm
 
 You can use CDN with module loading handler in JS API on your page.
 
-Just use `mappable.import`:
-
-```js
-const pkg = await mappable.import('@mappable-world/mappable-default-ui-theme');
-```
-
 By default `mappable.import` can load self modules.
-If you want also load your package, should add `loader`:
+Just use `mappable.registerCdn` and `mappable.import`:
 
 ```js
-// Add loader at start loaders array
-mappable.import.loaders.unshift(async (pkg) => {
-    // Process only your package
-    if (!pkg.includes('@mappable-world/mappable-default-ui-theme')) return;
+// register in `mappable.import` which CDN to take the package from
+mappable.import.registerCdn(
+  'https://cdn.jsdelivr.net/npm/{package}',
+  '@mappable-world/mappable-default-ui-theme@latest'
+);
 
-    // Load script directly. You can use another CDN
-    await mappable.import.script(`https://unpkg.com/${pkg}/dist/index.js`);
+// ...
 
-    // Return result object
-    return window['@mappable-world/mappable-default-ui-theme'];
-});
+// import package from CDN
+const pkg = await mappable.import('@mappable-world/mappable-default-ui-theme');
 ```
+
+## More about working with the package
+
+Read more about working with the package in the [documentation](https://mappable-world.github.io/mappable-default-ui-theme/).

example/README.md

@@ -0,0 +1,113 @@
+# Working with the package
+
+This package contains a range of pre-designed user interface elements for your map.
+This guide will provide you with detailed instructions on how to incorporate these
+elements into your map and customize them to suit your specific requirements.
+Live examples of how they can be used, along with links to the relevant code, will also be provided.
+
+## Controls
+
+This section presents all UI components that belong to the category of controls.
+These include simple zoom and tilt controls, as well as more advanced controls such as the search control.
+
+### Simple controls
+
+This type of controls includes the following:
+
+- `MMapGeolocationControl` – Display geolocation control on a map
+- `MMapZoomControl` – Display zoom control on a map
+- `MMapRotateControl` – Display rotate control on a map
+- `MMapTiltControl` – Display tilt control on a map
+- `MMapRotateTiltControl` – Display rotate and tilt in one control
+
+The `MMapZoomControl`, `MMapRotateControl`, `MMapTiltControl`, `MMapRotateTiltControl` controls have the same props:
+
+| Props name | Description                                           |
+| ---------- | ----------------------------------------------------- |
+| easing     | Easing function for map location animation (optional) |
+| duration   | Map location animate duration (optional)              |
+
+The parameters for the `MMapGeolocationControl` are slightly different:
+
+| Props name          | Description                                |
+| ------------------- | ------------------------------------------ |
+| onGeolocatePosition | Geolocation request callback               |
+| source              | Data source id for geolocation placemark   |
+| easing              | Easing function for map location animation |
+| duration            | Map location animate duration              |
+
+See a [live-example](./controls/vanilla/index.html) with simple controls.
+
+### Rich controls
+
+More comprehensive controls include the following classes::
+
+- `MMapSearchControl` – adds a control to the map in the form of a search bar.
+  It also has built-in suggest hints when entering the name of a place or organization.
+
+`MMapSearchControl` has the following parameters:
+
+| Props name   | Description                                                                           |
+| ------------ | ------------------------------------------------------------------------------------- |
+| search       | A function that overrides the search function. By default, `mappable.search` is used. |
+| suggest      | A function that overrides the hint function. By default, `mappable.suggest` is used   |
+| searchResult | The callback that receives the search results.                                        |
+
+`MMapSearchControl` does not display markers on the map, it only returns coordinates and location parameters,
+the developer is responsible for displaying them on the map.
+There is a [live example](./search-control/vanilla/index.html) that demonstrates the possibilities of search control.
+
+## Markers and popups
+
+Markers are UI components that are linked to a coordinate on the map.
+These components include the following classes:
+
+- `MMapDefaultMarker` – a marker on the map. It can be of different sizes and contain an icon from a ready-made preset.
+- `MMapPopupMarker` – a pop-up on the map with custom content.
+  It may have a different position relative to the point it points to.
+
+All markers have parameters from the [MMapMarker](https://mappable.world/docs/js-api/ref/index.html#MMapMarkerProps) base class.
+But there are also specific parameters for each type of marker.
+
+For `MMapDefaultMarker`:
+
+| Props name | Description                                                                                                                                            |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| iconName   | The name of the icon from the ready-made [icons preset](https://github.com/mappable-world/mappable-default-ui-theme/blob/main/docs/icons.generated.md) |
+| color      | The name of the color from the ready-made colors preset or an object indicating the color for the day and night mode                                   |
+| size       | The size of the marker. 3 sizes are available: `normal`, `small`, `micro`;                                                                             |
+| title      | The title to display in the marker hint                                                                                                                |
+| subtitle   | The subtitle to display in the marker hint                                                                                                             |
+| staticHint | A flag to indicate that the hint is static or appears when the mouse hovers over the marker                                                            |
+| popup      | The parameters for the embedded got into the marker                                                                                                    |
+
+There are 2 live examples for `MMapDefaultMarker`:
+
+- [Displaying markers on the map](./default-markers/vanilla/index.html)
+- [Pop-up displays at the marker](./marker-popup/vanilla/index.html)
+
+For `MMapPopupMarker`:
+
+| Props name | Description                                                                     |
+| ---------- | ------------------------------------------------------------------------------- |
+| content    | The function of creating popup content                                          |
+| position   | The position of the popup in relation to the point it is pointing to            |
+| offset     | The offset in pixels between the popup pointer and the point it is pointing to. |
+| show       | Hide or show popup on map                                                       |
+| onClose    | Popup closing callback                                                          |
+| onOpen     | Popup opening callback                                                          |
+
+There is a [live example](./popups-on-map/vanilla/index.html) for `MMapPopupMarker` to demonstrate the possibilities of its operation.
+
+## Examples
+
+- [Add controls to the map](./controls/vanilla/index.html)
+  ([source code](https://github.com/mappable-world/mappable-default-ui-theme/tree/main/example/controls))
+- [Add markers to the map](./default-markers/vanilla/index.html)
+  ([source code](https://github.com/mappable-world/mappable-default-ui-theme/tree/main/example/default-markers))
+- [Add a marker with a popup to the map](./marker-popup/vanilla/index.html)
+  ([source code](https://github.com/mappable-world/mappable-default-ui-theme/tree/main/example/marker-popup))
+- [Add a popup with custom content to the map](./popups-on-map/vanilla/index.html)
+  ([source code](https://github.com/mappable-world/mappable-default-ui-theme/tree/main/example/popups-on-map))
+- [Adding a search control to the map](./search-control/vanilla/index.html)
+  ([source code](https://github.com/mappable-world/mappable-default-ui-theme/tree/main/example/search-control))

example/case-template/common.ts

@@ -1,8 +1,9 @@
-import type {MMapLocationRequest, LngLatBounds} from '@mappable-world/mappable-types';
+import type {LngLat, LngLatBounds, MMapLocationRequest} from '@mappable-world/mappable-types';
 
 const BOUNDS: LngLatBounds = [
     [54.58311, 25.9985],
     [56.30248, 24.47889]
 ];
+export const CENTER: LngLat = [55.44279, 25.24107];
 
 export const LOCATION: MMapLocationRequest = {bounds: BOUNDS};

example/case-template/react/index.tsx

@@ -1,4 +1,4 @@
-import {LOCATION} from '../common';
+import {CENTER, LOCATION} from '../common';
 
 window.map = null;
 
@@ -9,11 +9,9 @@ async function main() {
 
     const {MMap, MMapDefaultSchemeLayer, MMapDefaultFeaturesLayer, MMapControls} = reactify.module(mappable);
 
-    const {useState, useCallback} = React;
-
-    const {MMapZoomControl} = reactify.module(await mappable.import('@mappable-world/[email protected]'));
-
-    const {MMapButtonExample} = reactify.module(await mappable.import('@mappable-world/mappable-default-ui-theme'));
+    const {MMapDefaultMarker, MMapZoomControl} = reactify.module(
+        await mappable.import('@mappable-world/mappable-default-ui-theme')
+    );
 
     ReactDOM.render(
         <React.StrictMode>
@@ -23,17 +21,14 @@ async function main() {
     );
 
     function App() {
-        const [location, setLocation] = useState(LOCATION);
-        const onClick = useCallback(() => alert('Click!'), []);
-
         return (
-            <MMap location={location} ref={(x) => (map = x)}>
+            <MMap location={LOCATION} ref={(x) => (map = x)}>
                 <MMapDefaultSchemeLayer />
                 <MMapDefaultFeaturesLayer />
                 <MMapControls position="right">
                     <MMapZoomControl />
-                    <MMapButtonExample text={'My button'} onClick={onClick} />
                 </MMapControls>
+                <MMapDefaultMarker coordinates={CENTER} size="normal" iconName="fallback" />
             </MMap>
         );
     }

example/case-template/vanilla/index.ts

@@ -1,22 +1,18 @@
-import {LOCATION} from '../common';
+import {CENTER, LOCATION} from '../common';
 window.map = null;
 
 main();
 async function main() {
     await mappable.ready;
     const {MMap, MMapDefaultSchemeLayer, MMapDefaultFeaturesLayer, MMapControls} = mappable;
 
-    const {MMapZoomControl} = await mappable.import('@mappable-world/[email protected]');
-    const {MMapButtonExample} = await mappable.import('@mappable-world/mappable-default-ui-theme');
+    const {MMapDefaultMarker, MMapZoomControl} = await mappable.import('@mappable-world/mappable-default-ui-theme');
 
     map = new MMap(document.getElementById('app'), {location: LOCATION});
 
     map.addChild(new MMapDefaultSchemeLayer({}));
     map.addChild(new MMapDefaultFeaturesLayer({}));
 
-    map.addChild(
-        new MMapControls({position: 'right'})
-            .addChild(new MMapZoomControl({}))
-            .addChild(new MMapButtonExample({text: 'My button', onClick: () => alert('Click!')}))
-    );
+    map.addChild(new MMapControls({position: 'right'}).addChild(new MMapZoomControl({})));
+    map.addChild(new MMapDefaultMarker({coordinates: CENTER, size: 'normal', iconName: 'fallback'}));
 }

example/case-template/vue/index.ts

@@ -1,4 +1,4 @@
-import {LOCATION} from '../common';
+import {CENTER, LOCATION} from '../common';
 
 window.map = null;
 
@@ -9,34 +9,33 @@ async function main() {
 
     const {MMap, MMapDefaultSchemeLayer, MMapDefaultFeaturesLayer, MMapControls} = vuefy.module(mappable);
 
-    const {MMapZoomControl} = vuefy.module(await mappable.import('@mappable-world/[email protected]'));
-
-    const {MMapButtonExample} = vuefy.module(await mappable.import('@mappable-world/mappable-default-ui-theme'));
+    const {MMapDefaultMarker, MMapZoomControl} = vuefy.module(
+        await mappable.import('@mappable-world/mappable-default-ui-theme')
+    );
 
     const app = Vue.createApp({
         components: {
             MMap,
             MMapDefaultSchemeLayer,
             MMapDefaultFeaturesLayer,
             MMapControls,
-            MMapZoomControl,
-            MMapButtonExample
+            MMapDefaultMarker,
+            MMapZoomControl
         },
         setup() {
             const refMap = (ref: any) => {
                 window.map = ref?.entity;
             };
-            const onClick = () => alert('Click!');
-            return {LOCATION, refMap, onClick};
+            return {LOCATION, CENTER, refMap};
         },
         template: `
             <MMap :location="LOCATION" :ref="refMap">
                 <MMapDefaultSchemeLayer />
                 <MMapDefaultFeaturesLayer />
                 <MMapControls position="right">
                     <MMapZoomControl />
-                    <MMapButtonExample text="My button" :onClick="onClick" />
                 </MMapControls>
+                <MMapDefaultMarker :coordinates="CENTER" size="normal" iconName="fallback" />
             </MMap>`
     });
     app.mount('#app');

example/rotate-tilt-controls/common.ts → example/controls/common.ts

@@ -1,9 +1,9 @@
-import {BehaviorType, LngLatBounds, MMapBoundsLocation} from '@mappable-world/mappable-types';
+import type {MMapLocationRequest, LngLatBounds, BehaviorType} from '@mappable-world/mappable-types';
 
 const BOUNDS: LngLatBounds = [
     [54.58311, 25.9985],
     [56.30248, 24.47889]
 ];
 
-export const LOCATION: MMapBoundsLocation = {bounds: BOUNDS};
+export const LOCATION: MMapLocationRequest = {bounds: BOUNDS};
 export const ENABLED_BEHAVIORS: BehaviorType[] = ['drag', 'scrollZoom', 'dblClick', 'mouseTilt', 'mouseRotate'];