@unvt/charites 0.2.0 → 0.4.0

package/docs/source/usage/commandline_interface.rst

@@ -1,7 +1,7 @@
 Commandline Interface
 ======================
 
-help
+Help
 ----
 
 .. code-block:: bash
@@ -14,13 +14,22 @@ help
     -h, --help                              display help for command
 
     Commands:
-    init [options] <file>                   initialize a style JSON
+    init [options] <file>                   initialize a style YAML
     convert <source> [destination]          convert the style JSON to YAML
     build [options] <source> [destination]  build a style JSON from the YAML
     serve [options] <source>                serve your map locally
     help [command]                          display help for command
 
 
+Checking version
+-------------------
+
+.. code-block:: bash
+
+    $ charites --version
+    0.3.0
+
+
 Inititalize `style.yml`
 -----------------------
 
@@ -29,7 +38,7 @@ Inititalize `style.yml`
     $ charites init -h
     Usage: charites init [options] <file>
 
-    initialize a style JSON
+    initialize a style YAML
 
     Options:
     -t, --tilejson-urls <tilejson_urls>          an URL for TileJSON. It will create empty layers from vector_layers property of TileJSON. Please use
@@ -85,18 +94,22 @@ Realtime editor on browser
     serve your map locally
 
     Options:
-    --provider [provider]                      your map service. e.g. `mapbox`, `geolonia`
-    --mapbox-access-token [mapboxAccessToken]  Access Token for the Mapbox
-    --port [port]                              Specify custom port
-    -h, --help                                 display help for command
+    --provider [provider]                        your map service. e.g. `mapbox`, `geolonia`
+    --mapbox-access-token [mapboxAccessToken]    Access Token for the Mapbox
+    -i, --sprite-input [<icon input directory>]  directory path of icon source to build icons. The default <icon
+                                                 source> is `icons/`
+    --port [port]                                Specify custom port
+    -h, --help                                   display help for command
 
 Charites has three options for `serve` command.
 
-- `--provider` - `mapbox`, `geolonia`, or `default`. When not specified, default or the value in the configuration file will be used.
+- ``--provider`` - `mapbox`, `geolonia`, or `default`. When not specified, default or the value in the configuration file will be used.
 
   - `mapbox` - The format linter runs against the Mapbox GL JS v2.x compatible specification.
   - `geolonia` and `default` - the format linter runs against the MapLibre GL JS compatible specification.
 
-- `--mapbox-access-token` - Set your access-token when styling for Mapbox.
+- ``--mapbox-access-token`` - Set your access-token when styling for Mapbox.
+
+- ``--sprite-input`` - If you are building icon spritesheets with Charites, you can specify the directory of SVG files to compile here. See the ``build`` command for more information.
 
-- `--port` - Set http server's port number. When not specified, use 8080 port.
+- ``--port`` - Set http server's port number. When not specified, the default is 8080.

package/docs/source/usage/example2.rst

@@ -0,0 +1,166 @@
+Example 2: Import existing style.json and edit it with charites
+===================================================================
+This is an example of using charites for importing an existing style.json and editing it as yaml files, and exporting them back to a json style. 
+
+Condition
+------------------------
+- OS: Windows 10
+- Charites version: 0.3.0
+- Running on WindowsPowershell
+
+
+Steps
+-----
+
+
+Step 1. Import style json into a series of YAML files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your style json is in the Internet, it may need to downloat it from the Internet before you convert because charites cannot directly convert json a file in the Internet. Use curl.exe (in WindowsPowershell) or curl (in bash environment).
+
+.. code-block:: 
+
+    curl.exe -O https://ubukawa.github.io/cmv-test/style1.json
+    charites convert style1.json editing/style.yml
+
+Then, you will see a series of yaml files are converted from the source json. You will obtain an overall YAML that contains a list of style layers with the style yamls in the layer directory.  
+In this case, we will have "style.yml" in "editing" directory together with a lot of yaml files for layers in "layers" directory.
+
+.. image:: ./img/example02-001.png
+   :scale: 75%
+   :align: center
+
+.. image:: ./img/example02-002.png
+   :scale: 75%
+   :align: center
+
+(Tips) It is good to know that if your source json has some folder structure in its layer ids, that structure would be maintained when you import. 
+
+.. image:: ./img/example02-005.png
+   :scale: 75%
+   :align: center
+
+.. image:: ./img/example02-003.png
+   :scale: 75%
+   :align: center
+
+.. image:: ./img/example02-004.png
+   :scale: 75%
+   :align: center
+
+Step 2. Checking an overall yaml (style.yml in this case)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Check the style.yml by opening it with Notepad or any text editor. You will see it like this:
+
+.. image:: ./img/example02-006.png
+   :scale: 75%
+   :align: center
+
+Although it is not often seen, we need to check one thing. Sometimes, if id for each layer is too long, YAML automatically uses ">-" and break the line to improve human's readability. ">-" would pretend an actual line break in YAML, however, it will cause some problem for Charites, so please fix line brakes with ">-" in the layers if you find them.
+This is often seen in style files from Esri vector tile because it has detailed folder structure sometimes.
+
+.. image:: ./img/example02-007.png
+   :scale: 75%
+   :align: center
+
+.. image:: ./img/example02-008.png
+   :scale: 75%
+   :align: center
+
+You can extract layers and use "replace" tool to remove ">-" and unnecessary line changes.
+
+.. image:: ./img/example02-009.png
+   :scale: 75%
+   :align: center
+
+.. image:: ./img/example02-010.png
+   :scale: 75%
+   :align: center
+
+If you obtain the list of layers without ">-", you are ready to go to the next step.
+
+.. image:: ./img/example02-011.png
+   :scale: 75%
+   :align: center
+
+.. note::
+
+    You may also need to check paths in "sprite", "glyphs" and "sources." They would be written as relative paths, so you may need to adjust these paths so that charites in your local PC can access to them. In addition, if you are importing styles from ArcGIS server, reference to the source should be modifyed (use "tiles" instead of "url"). The "tiles" URL will be provided by adding "/tile/{z}/{y}/{x}.pbf" in the end of Esri vector tile server URL.
+
+
+Step 3. Serve YAML files for live preview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Run the "charites serve" command to serve your YAML files in the localhost. By default, its port is 8080.
+
+.. code-block:: 
+
+    charites serve editing/style.yml
+
+A window would automatically appears in the windows environment, but if not please open "http://localhost:8080" to access your live view. You can stop the live preview by pressing ctrl + c.
+
+.. image:: ./img/example02-012.png
+   :scale: 75%
+   :align: center
+
+Step 4. Editing YAML files to change style
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can change/edit the map style by editing YAML files. If you edit and save your update, charites automatically finds your updates to reflect them into the live view.
+
+.. image:: ./img/example02-016.png
+   :scale: 75%
+   :align: center
+
+Here are some tips for efficient style editing.
+
+(Tips 1) Legend control
+########################
+There is a legend control in the lower left of the screen. You can turn on/off any layers so that your edit would be easy. It will also help you to identify layers that should be edited.
+You can enlarge the window by clicking the button, and reduce its size by clicking "x" in the window. You can also choose to list only rendered layers or not in the window. 
+
+.. image:: ./img/example02-013.png
+   :scale: 75%
+   :align: center
+
+(Tips 2) Showing tile boundary
+###############################
+It would be alos helpful to show the tile boundary. There are checkbox in the upper left, and you can turn on/off. You will see tile border and its xyx in z/x/y order together with tile size. This would be useful when you also think about optimization of your vector tile.
+
+.. image:: ./img/example02-014.png
+   :scale: 75%
+   :align: center
+
+(Tips 3) Showing collision boxes
+#################################
+It would be alos helpful to show the collision boxes. If a box is red, it indicates a collision with others. When you adjust label location/size, this is good.
+
+.. image:: ./img/example02-015.png
+   :scale: 75%
+   :align: center
+
+(Tips 4) Use of "#" (comment tag) to specify error
+###################################################
+If there is a layer contains some error, the web map may not appears. In such a case, use a YAML comment tag "#" to comment out a layer (or layers) to specify the layer contains an error. The comment tag is also useful to tentatively change colors, etc.
+
+(Tips 5) Use of inclusion of other YAML file for efficinet edit
+################################################################
+If you repeatedly use the same expression (color, font, etc) for several layers, it is conveninet to use a reference to a common expression. You can do it by using inclusion of  an independent YAML file with "!!inc/file hogehoge.yml". This is particular important if you manage your style with YAML files.
+
+.. image:: ./img/example02-017.png
+   :scale: 75%
+   :align: center
+
+.. image:: ./img/example02-018.png
+   :scale: 75%
+   :align: center
+
+Step 5. Exporting style json from YAML files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Once you have edited your style with YAML files, you can now export it back to json by running the following command.
+
+.. code-block:: 
+
+    charites build editing/style.yml out.json
+
+Congratulations. You will obtain the updated style json, and all done.
+

package/docs/source/usage/examples.rst

@@ -29,14 +29,14 @@ Build `style.json` from `style.yml`:
 
     charites build style.yml style.json
 
-Add `-c` or `--compact-output` to minify the JSON
+Add ``-c`` or ``--compact-output`` to minify the JSON
 
 .. code-block:: bash
 
     charites build style.yml style.json -c
 
 
-Add `--sprite-input` and `--sprite-output` to build svg files for map icons.
+Add ``--sprite-input`` and ``--sprite-output`` to build svg files for map icons.
 
 .. code-block:: bash
 

package/docs/source/usage/index.rst

@@ -8,3 +8,4 @@ Usage
   commandline_interface
   global_options
   examples
+  example2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unvt/charites",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "",
   "bin": {
     "charites": "dist/cli.js"
@@ -9,45 +9,51 @@
     "build": "tsc -p .",
     "watch": "tsc -w",
     "lint": "eslint --fix .",
-    "test": "npm run build && mocha -r ts-node/register test/*.ts",
+    "test": "npm run build && mocha --timeout 5000 -r ts-node/register test/*.ts",
     "test:watch": "npm test -- --watch --watch-files src/**/*.ts --watch-files test/**/*.ts",
+    "test:e2e": "npx playwright test",
     "command": "./node_modules/.bin/ts-node ./src/cli.ts"
   },
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@mapbox/mapbox-gl-style-spec": "^13.22.0",
-    "@maplibre/maplibre-gl-style-spec": "^14.0.2",
-    "@unvt/sprite-one": "^0.0.6",
+    "@mapbox/mapbox-gl-style-spec": "^13.27.0",
+    "@maplibre/maplibre-gl-style-spec": "^17.0.2",
     "@types/jsonminify": "^0.4.1",
-    "axios": "^0.24.0",
-    "commander": "^8.2.0",
-    "glob": "^7.2.0",
+    "@unvt/sprite-one": "^0.0.9",
+    "axios": "^1.2.2",
+    "commander": "^9.4.1",
+    "glob": "^8.0.3",
     "js-yaml": "^4.0.0",
-    "jsonminify": "^0.4.1",
-    "node-watch": "^0.7.2",
+    "jsonminify": "^0.4.2",
+    "node-watch": "^0.7.3",
     "open": "^8.2.1",
-    "ws": "^8.2.2",
+    "ws": "^8.11.0",
     "yaml-include": "^1.2.1"
   },
   "devDependencies": {
-    "@types/chai": "^4.2.11",
+    "@playwright/test": "^1.29.1",
+    "@types/chai": "^4.3.4",
+    "@types/chai-as-promised": "^7.1.5",
     "@types/fs-extra": "^9.0.13",
-    "@types/js-yaml": "^4.0.3",
-    "@types/mocha": "^7.0.2",
-    "@types/node": "^14.0.14",
-    "@types/ws": "^8.2.0",
-    "@typescript-eslint/eslint-plugin": "^4.16.1",
-    "@typescript-eslint/parser": "^4.16.1",
-    "chai": "^4.2.0",
-    "eslint": "^7.21.0",
-    "eslint-config-prettier": "^6.15.0",
-    "eslint-plugin-prettier": "^3.3.1",
-    "fs-extra": "^10.0.0",
-    "kill-port-process": "^3.0.1",
-    "mocha": "^8.0.1",
-    "prettier": "^2.5.0",
-    "ts-node": "^8.10.2",
-    "typescript": "^3.9.5"
+    "@types/js-yaml": "^4.0.5",
+    "@types/mapbox__point-geometry": "^0.1.2",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "^18.11.18",
+    "@types/ws": "^8.5.4",
+    "@typescript-eslint/eslint-plugin": "^5.47.1",
+    "@typescript-eslint/parser": "^5.47.1",
+    "chai": "^4.3.7",
+    "chai-as-promised": "^7.1.1",
+    "eslint": "^8.31.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-prettier": "^4.2.1",
+    "fs-extra": "^11.1.0",
+    "kill-port-process": "^3.1.0",
+    "mocha": "^10.2.0",
+    "node-abort-controller": "^3.0.1",
+    "prettier": "^2.8.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.4"
   }
 }

package/playwright.config.ts

@@ -0,0 +1,29 @@
+// playwright.config.ts
+import type { PlaywrightTestConfig } from '@playwright/test'
+
+const config: PlaywrightTestConfig = {
+  testDir: 'test/playwright',
+  use: {
+    browserName: 'chromium',
+    headless: true,
+  },
+  workers: 3,
+  webServer: [
+    {
+      command: 'dist/cli.js serve test/data/style.yml --port 8080',
+      port: 8080,
+    },
+    {
+      command:
+        'dist/cli.js serve test/data/style.yml --provider geolonia --port 8088',
+      port: 8088,
+    },
+    {
+      command:
+        'dist/cli.js serve test/data/style.yml --provider mapbox --port 8888 --mapbox-access-token ' +
+        process.env.MAPBOX_ACCESS_TOKEN,
+      port: 8888,
+    },
+  ],
+}
+export default config

package/provider/default/app.js

@@ -1,50 +1,30 @@
-const map = new maplibregl.Map({
-  container: 'map',
-  hash: true,
-  style: `http://${window.location.host}/style.json`,
-})
+;(async () => {
+  const { style, center, zoom } = await window._charites.parseMapStyle()
+  const options = {
+    container: 'map',
+    hash: true,
+    style,
+  }
+  if (center) options.center = center
+  if (zoom) options.zoom = zoom
+  const map = new maplibregl.Map(options)
 
-const socket = new WebSocket('ws://localhost:___PORT___')
+  window._charites.initializeWebSocket(map)
 
-socket.addEventListener('message', (message) => {
-  map.setStyle(JSON.parse(message.data))
-})
+  map.addControl(new maplibregl.NavigationControl(), 'top-right')
 
-map.addControl(new maplibregl.NavigationControl(), 'top-right')
+  map.addControl(
+    new MaplibreLegendControl(
+      {},
+      {
+        showDefault: true,
+        showCheckbox: true,
+        onlyRendered: true,
+        reverseOrder: true,
+      },
+    ),
+    'bottom-left',
+  )
 
-map.addControl(
-  new watergis.MaplibreLegendControl(
-    {},
-    {
-      showDefault: true,
-      showCheckbox: true,
-      onlyRendered: true,
-      reverseOrder: true,
-    },
-  ),
-  'bottom-left',
-)
-
-const showTileBoundaries = document.getElementById('showTileBoundaries')
-const setShowTileBoundaries = function () {
-  const checked = showTileBoundaries.checked
-  map.showTileBoundaries = checked
-}
-setShowTileBoundaries()
-showTileBoundaries.addEventListener('click', setShowTileBoundaries)
-
-const showCollisionBoxes = document.getElementById('showCollisionBoxes')
-const setShowCollisionBoxes = function () {
-  const checked = showCollisionBoxes.checked
-  map.showCollisionBoxes = checked
-}
-setShowCollisionBoxes()
-showCollisionBoxes.addEventListener('click', setShowCollisionBoxes)
-
-const showPadding = document.getElementById('showPadding')
-const setShowPadding = function () {
-  const checked = showPadding.checked
-  map.showPadding = checked
-}
-setShowPadding()
-showPadding.addEventListener('click', setShowPadding)
+  window._charites.setupDebugCheckboxes(map)
+})()

package/provider/default/index.html

@@ -1,11 +1,11 @@
 <!DOCTYPE html>
-<html>
+<html id="charites-default">
   <head>
     <link rel="stylesheet" href="/app.css" />
-    <link href='https://unpkg.com/maplibre-gl@1.15.2/dist/maplibre-gl.css' rel='stylesheet' />
+    <link href='https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css' rel='stylesheet' />
     <link href='https://watergis.github.io/maplibre-gl-legend/maplibre-gl-legend.css' rel='stylesheet' />
     <title>Charites Live Preview</title>
-    <script src='https://unpkg.com/maplibre-gl@1.15.2/dist/maplibre-gl.js'></script>
+    <script src='https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js'></script>
     <script src="https://watergis.github.io/maplibre-gl-legend/maplibre-gl-legend.js"></script>
   </head>
   <body>
@@ -17,6 +17,7 @@
       <label><input type="checkbox" id="showPadding">show Padding</label>
     </div>
     <div id="map"></div>
+    <script type="text/javascript" src="/shared.js"></script>
     <script type="text/javascript" src="/app.js"></script>
   </body>
 </html>

package/provider/default/shared.js

@@ -0,0 +1,76 @@
+;(async () => {
+  window._charites = {
+    initializeWebSocket: function (map) {
+      const socket = new WebSocket(`ws://${window.location.host}`)
+
+      socket.addEventListener('message', (message) => {
+        const data = JSON.parse(message.data)
+        if (data.event === 'styleUpdate') {
+          map.setStyle(`http://${window.location.host}/style.json`)
+        } else if (data.event === 'spriteUpdate') {
+          map.setStyle(`http://${window.location.host}/style.json`, {
+            diff: false,
+          })
+        }
+      })
+    },
+    parseMapStyle: async function () {
+      const mapStyleUrl = `http://${window.location.host}/style.json`
+      const mapStyleRes = await fetch(mapStyleUrl)
+      const mapStyleJson = await mapStyleRes.json()
+
+      // detect center & zoom from map style json
+      let center = mapStyleJson.hasOwnProperty('center')
+        ? mapStyleJson.center
+        : undefined
+      let zoom = mapStyleJson.hasOwnProperty('zoom')
+        ? mapStyleJson.zoom
+        : undefined
+
+      // detect center & zoom from tile json
+      if (center === undefined || zoom === undefined) {
+        for (const sourceName in mapStyleJson.sources) {
+          if (
+            mapStyleJson.sources[sourceName].type === 'vector' &&
+            mapStyleJson.sources[sourceName].hasOwnProperty('url')
+          ) {
+            const mapTileUrl = mapStyleJson.sources[sourceName].url
+            const mapTileRes = await fetch(mapTileUrl)
+            const mapTileJson = await mapTileRes.json()
+            if (center === undefined) {
+              const bounds = mapTileJson.bounds
+              center = mapTileJson.center
+                ? mapTileJson.center
+                : [(bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2]
+            }
+            if (zoom === undefined) {
+              zoom = (mapTileJson.minzoom + mapTileJson.maxzoom) / 2
+            }
+          }
+        }
+      }
+
+      return {
+        style: mapStyleUrl,
+        center,
+        zoom,
+      }
+    },
+    setupDebugCheckboxes: function (map) {
+      const properties = [
+        'showTileBoundaries',
+        'showCollisionBoxes',
+        'showPadding',
+      ]
+      for (const property of properties) {
+        const control = document.getElementById(property)
+        const clickHandler = function () {
+          const checked = control.checked
+          map[property] = checked
+        }
+        clickHandler()
+        control.addEventListener('click', clickHandler)
+      }
+    },
+  }
+})()

package/provider/geolonia/app.js

@@ -1,35 +1,28 @@
-const map = new geolonia.Map({
-  container: '#map',
-  hash: true,
-  style: `http://${window.location.host}/style.json`,
-})
+;(async () => {
+  const { style, center, zoom } = await window._charites.parseMapStyle()
+  const options = {
+    container: 'map',
+    hash: true,
+    style,
+  }
+  if (center) options.center = center
+  if (zoom) options.zoom = zoom
+  const map = new geolonia.Map(options)
 
-const socket = new WebSocket('ws://localhost:___PORT___')
+  window._charites.initializeWebSocket(map)
 
-socket.addEventListener('message', (message) => {
-  map.setStyle(JSON.parse(message.data))
-})
+  map.addControl(
+    new MaplibreLegendControl(
+      {},
+      {
+        showDefault: true,
+        showCheckbox: true,
+        onlyRendered: true,
+        reverseOrder: true,
+      },
+    ),
+    'bottom-left',
+  )
 
-const showTileBoundaries = document.getElementById('showTileBoundaries')
-const setShowTileBoundaries = function () {
-  const checked = showTileBoundaries.checked
-  map.showTileBoundaries = checked
-}
-setShowTileBoundaries()
-showTileBoundaries.addEventListener('click', setShowTileBoundaries)
-
-const showCollisionBoxes = document.getElementById('showCollisionBoxes')
-const setShowCollisionBoxes = function () {
-  const checked = showCollisionBoxes.checked
-  map.showCollisionBoxes = checked
-}
-setShowCollisionBoxes()
-showCollisionBoxes.addEventListener('click', setShowCollisionBoxes)
-
-const showPadding = document.getElementById('showPadding')
-const setShowPadding = function () {
-  const checked = showPadding.checked
-  map.showPadding = checked
-}
-setShowPadding()
-showPadding.addEventListener('click', setShowPadding)
+  window._charites.setupDebugCheckboxes(map)
+})()