@unvt/charites 0.1.2 → 0.1.3

package/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

package/docs/source/conf.py

@@ -0,0 +1,69 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'charites'
+copyright = '2021, The United Nations Vector Tile Toolkit'
+author = 'Jin Igarashi'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1.2'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx_rtd_theme',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+locale_dirs = ['../i18n/']     # path is example but recommended.
+gettext_compact = False     # optional.
+
+# Adding “Edit Source” links on your Sphinx theme
+# https://docs.readthedocs.io/en/stable/guides/edit-source-links-sphinx.html
+html_context = {
+    "display_github": True, # Integrate GitHub
+    "github_user": "unvt", # Username
+    "github_repo": "charites", # Repo name
+    "github_version": "main", # Version
+    "conf_py_path": "/docs/source/", # Path in the checkout to the docs root
+}

package/docs/source/development/index.rst

@@ -0,0 +1,40 @@
+Development
+===========
+
+Build from source code
+----------------------
+
+The following procedures is how to build and install charites from source code.
+
+.. code-block:: bash
+
+    $ git clone https://github.com/unvt/charites.git
+    $ cd charites
+    $ npm install
+    $ npm run build
+    $ npm install -g .
+
+
+.. warning::
+    if you have already installed other version's `charites` from npm globally, it might occur some conflicts. Please uninstall all charites from globally by using following commands before installing development version.
+
+.. code-block:: bash
+    
+    npm uninstall -g .
+    npm uninstall -g @unvt/charites
+
+Then run:
+
+.. code-block:: bash
+
+    $ charites help
+
+
+Releasing this package
+----------------------
+
+.. code-block:: bash
+
+    $ npm version patch # Or `minor` or `major`
+    $ git push
+    $ git push origin <version>

package/docs/source/index.rst

@@ -0,0 +1,61 @@
+.. charites documentation master file, created by
+   sphinx-quickstart on Wed Dec  8 09:24:35 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Charites - Documentation
+====================================
+
+:Date:   2021-12-08
+:Copyright: CC-BY-SA
+:Organization: The United Nations Vector Tile Toolkit
+:Version: 0.1.2
+:Abstract: This document contains the complete documentation of Charites, an application to style vector tiles easily
+
+.. meta::
+   :description lang=en: This document contains the complete documentation of Charites, an application to style vector tiles easily
+   :keywords: Charites, Mapbox, Maplibre, Vectortiles, UNVT, webmapping
+
+An easy, intuitive, and efficient command-line tool for writing vector map styles compatible with the `Mapbox <https://docs.mapbox.com/mapbox-gl-js/style-spec/>`_ and `MapLibre <https://maplibre.org/maplibre-gl-js-docs/style-spec/>`_ Style Specification in YAML.
+With YAML format's readability, JSON compiler, linter, and live style viewer on a local browser, you can simplify your map styling workflow.
+
+.. note::
+   In Greek mythology, the `Charites <https://en.wikipedia.org/wiki/Charites>`_ are the three goddesses of charm, beauty, and human creativity. They are believed to have been worshipped not only by artists but also by those who aspired to technology to infuse them with a creative spirit.
+
+Features
+==================
+
+- Initiate a project from scratch, or convert an existing `style.json` file to generate YAML style files.
+- Write styles in a simple YAML format.
+- Divide groups of layers in to multiple files for better readability and mantainability. `!!inc/file <relative-path-to-the-file>`
+- Use variables like `$backgroundColor` and `$waterColor` to style effectively.
+- Compile YAML to a single style.json file, with a format linter.
+- Use `--provider mapbox` to validate your style against Mapbox GL JS v2.x
+- Run `charites serve <source>` to preview your style live while you make changes in a browser.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   install/index
+   usage/index
+   development/index
+
+Translations
+============
+
+The documentation is available in several languages.
+
+- `English </charites/en>`_
+- `日本語 </charites/ja>`_
+- `Français </charites/fr>`_
+- `عربى </charites/ar>`_
+
+If there is an error with a translation, please `help to improve it <https://www.transifex.com/unvt/charites-docs/>`_.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

package/docs/source/install/index.rst

@@ -0,0 +1,10 @@
+==================================
+Installing Charites
+==================================
+
+.. toctree::
+  :maxdepth: 1
+
+  recommended_environment
+  install
+  install_on_nanban

package/docs/source/install/install.rst

@@ -0,0 +1,7 @@
+Install
+=======
+
+.. code-block:: bash
+
+    $ npm install -g @unvt/charites
+    $ charites help

package/docs/source/install/install_on_nanban.rst

@@ -0,0 +1,9 @@
+charites on unvt/nanban
+=======================
+
+Charites runs on Docker with one of UNVT tools named `unvt/nanban <https://github.com/unvt/nanban>`_.
+
+.. code-block:: bash
+
+    $ docker run -ti --rm -v ${PWD}:/data -p 8080:8080 unvt/nanban
+    $ cd /data

package/docs/source/install/recommended_environment.rst

@@ -0,0 +1,6 @@
+Recommended environment
+=======================
+
+Chrities may work well on OSX, Ubuntu, but it might not work well in some envrionment such as arm64 (eg., M1 Mac) because some of NPM packages like sprite-zero uses mapnik.  
+
+Docker can be the good environment in Windows while WSL might work well.

package/docs/source/usage/commandline_interface.rst

@@ -0,0 +1,99 @@
+Commandline Interface
+======================
+
+help
+----
+
+.. code-block:: bash
+
+    $ charites help
+    Usage: charites [options] [command]
+
+    Options:
+    -v, --version                           output the version number
+    -h, --help                              display help for command
+
+    Commands:
+    init [options] <file>                   initialize a style JSON
+    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
+
+
+Inititalize `style.yml`
+-----------------------
+
+.. code-block:: bash
+
+    $ charites init -h
+    Usage: charites init [options] <file>
+
+    initialize a style JSON
+
+    Options:
+    -t, --tilejson-urls <tilejson_urls>          an URL for TileJSON. It will create empty layers from vector_layers property of TileJSON. Please use
+                                                comma (,) in case multiple TileJSONs require.
+    -m, --metadatajson-urls <metadatajson_urls>  an URL for metadata.json. It will create empty layers from vector_layers property of metadata.json.
+                                                Please use comma (,) in case multiple metadata.json require.
+    -c, --composite-layers                       If it is true, a single YAML will be generated with multiple layers. Default is false.
+    -h, --help                                   display help for command
+
+
+Convert existing `style.json`
+-----------------------------
+
+.. code-block:: bash
+
+    $ charites convert -h
+    Usage: charites convert [options] <source> [destination]
+
+    convert the style JSON to YAML
+
+    Options:
+    -h, --help  display help for command
+
+Build `style.json` from `style.yml`
+-----------------------------------
+
+.. code-block:: bash
+
+    charites build -h
+    Usage: charites build [options] <source> [destination]
+
+    build a style JSON from the YAML
+
+    Options:
+    -c, --compact-output                           build a minified style JSON
+    -w, --watch                                    watch YAML and build when changed
+    -u, --sprite-url [<sprite url>]                url to set as the sprite in style.json
+    -i, --sprite-input [<icon input directory>]    directory path of icon source to build icons. The default <icon source> is `icons/`
+    -o, --sprite-output [<icon output directory>]  directory path to output icon files. The default <icons destination> is the current directory
+    --provider [provider]                          your map service. e.g. `mapbox`, `geolonia`
+    -h, --help                                     display help for command
+
+if you use mapbox v2 for your style, please use `--provider mapbox` to specify mapbox service rather than default. Please see `--provider` option at `serve` command section.
+
+Realtime editor on browser
+--------------------------
+
+.. code-block:: bash
+
+    charites serve -h
+    Usage: charites serve [options] <source>
+
+    serve your map locally
+
+    Options:
+    --provider [provider]                      your map service. e.g. `mapbox`, `geolonia`
+    --mapbox-access-token [mapboxAccessToken]  Access Token for the Mapbox
+    -h, --help                                 display help for command
+
+Charites has two options for `serve` command.
+
+- `--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.

package/docs/source/usage/examples.rst

@@ -0,0 +1,74 @@
+Examples
+========
+
+Example: https://github.com/geoloniamaps/basic
+
+init
+------
+
+Initialize `style.yml` from either TileJSON or metadata.json.
+If you do not specify TileJSON URL, it will generate empty `style.yml`.
+
+.. code-block:: bash
+
+    charites init style.yml --tilejson-urls https://raw.githubusercontent.com/mapbox/tilejson-spec/master/3.0.0/example/osm.json
+
+
+.. code-block:: bash
+
+    charites init style.yml --metadatajson-urls https://optgeo.github.io/kokoromi-rw/zxy/metadata.json
+
+In `init` command, you can just generate a single YAML instead of creating layer configuration files separately when you add optional `-c` or `--composite-layers` parameter.
+
+build
+-------
+
+Build `style.json` from `style.yml`:
+
+.. code-block:: bash
+
+    charites build style.yml style.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.
+
+.. code-block:: bash
+
+    charites build style.yml style.json --sprite-input icons/ --sprite-output public/
+
+
+Convert `style.json` to `style.yml`
+------------------------------------
+
+.. code-block:: bash
+
+    charites convert style.json style.yml
+
+
+Load JSON as a standard input to generate `style.yml`:
+
+.. code-block:: bash
+
+    curl http://example.com/style.json | charites convert - style.yml
+
+serve
+-------
+
+Launch a live preview of your map style in your local environment:
+
+.. code-block:: bash
+
+    charites serve style.yml
+
+
+For Mapbox users:
+
+.. code-block:: bash
+
+    charites serve style.yml --provider mapbox --mapbox-access-token xxxx

package/docs/source/usage/global_options.rst

@@ -0,0 +1,21 @@
+Global configuration
+====================
+
+Some options for Charites can be stored in a configuration file written in YAML.
+
+The config file will be automatically created to the following path the first time the charites command is executed.
+
+.. code-block:: bash
+
+    ~/.charites/config.yml
+
+
+Global options can be specified as follows:
+
+.. code-block:: bash
+
+    provider: mapbox
+    mapboxAccessToken: xxxx
+
+
+With the example above, you get the same result as `charites serve --provider mapbox --mapbox-access-token xxxx`.

package/docs/source/usage/index.rst

@@ -0,0 +1,10 @@
+==================================
+Usage
+==================================
+
+.. toctree::
+  :maxdepth: 1
+
+  commandline_interface
+  global_options
+  examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unvt/charites",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "",
   "bin": {
     "charites": "dist/cli.js"
@@ -8,19 +8,21 @@
   "scripts": {
     "build": "tsc -p .",
     "watch": "tsc -w",
-    "lint": "eslint .",
-    "fix": "eslint --fix .",
+    "lint": "eslint --fix .",
     "test": "mocha -r ts-node/register test/*.ts",
     "test:watch": "npm test -- --watch --watch-files src/**/*.ts --watch-files test/**/*.ts",
-    "command": "./node_modules/.bin/ts-node ./src/cli.ts"
+    "command": "./node_modules/.bin/ts-node ./src/cli"
   },
   "author": "",
   "license": "MIT",
   "dependencies": {
     "@mapbox/mapbox-gl-style-spec": "^13.22.0",
+    "@mapbox/spritezero": "^8.0.0",
     "@maplibre/maplibre-gl-style-spec": "^14.0.2",
     "@types/jsonminify": "^0.4.1",
+    "axios": "^0.24.0",
     "commander": "^8.2.0",
+    "glob": "^7.2.0",
     "js-yaml": "^4.0.0",
     "jsonminify": "^0.4.1",
     "node-watch": "^0.7.2",
@@ -34,8 +36,14 @@
     "@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",
     "mocha": "^8.0.1",
+    "prettier": "^2.5.0",
     "ts-node": "^8.10.2",
     "typescript": "^3.9.5"
   }

package/provider/default/app.css

@@ -5,3 +5,13 @@ html, body, #map
   padding: 0;
   margin: 0;
 }
+
+.overlay {
+  width: 200px;
+  position: absolute;
+  top: 10;
+  left: 10;
+  margin: 5px;
+  z-index: 90;
+  background-color: rgba(255, 255, 255, 0.6);
+}

package/provider/default/app.js

@@ -1,11 +1,37 @@
 const map = new maplibregl.Map({
   container: 'map',
   hash: true,
-  style: `http://${window.location.host}/style.json`
-});
+  style: `http://${window.location.host}/style.json`,
+})
 
-const socket = new WebSocket('ws://localhost:___PORT___');
+const socket = new WebSocket('ws://localhost:___PORT___')
 
-socket.addEventListener('message',(message)=>{
+socket.addEventListener('message', (message) => {
   map.setStyle(JSON.parse(message.data))
-});
+})
+
+map.addControl(new maplibregl.NavigationControl(), 'top-right')
+
+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)

package/provider/default/index.html

@@ -7,6 +7,13 @@
     <script src='https://unpkg.com/maplibre-gl@1.15.2/dist/maplibre-gl.js'></script>
   </head>
   <body>
+    <div class="overlay">
+      <label><input type="checkbox" id="showTileBoundaries">show Tile Boundaries</label>
+      <br>
+      <label><input type="checkbox" id="showCollisionBoxes">show Collision Boxes</label>
+      <br>
+      <label><input type="checkbox" id="showPadding">show Padding</label>
+    </div>
     <div id="map"></div>
     <script type="text/javascript" src="/app.js"></script>
   </body>

package/provider/geolonia/app.css

@@ -5,3 +5,13 @@ html, body, #map
   padding: 0;
   margin: 0;
 }
+
+.overlay {
+  width: 200px;
+  position: absolute;
+  top: 10;
+  left: 10;
+  margin: 5px;
+  z-index: 90;
+  background-color: rgba(255, 255, 255, 0.6);
+}

package/provider/geolonia/app.js

@@ -1,11 +1,35 @@
 const map = new geolonia.Map({
-  container: "#map",
+  container: '#map',
   hash: true,
-  style: `http://${window.location.host}/style.json`
+  style: `http://${window.location.host}/style.json`,
 })
 
-const socket = new WebSocket('ws://localhost:___PORT___');
+const socket = new WebSocket('ws://localhost:___PORT___')
 
-socket.addEventListener('message',(message)=>{
+socket.addEventListener('message', (message) => {
   map.setStyle(JSON.parse(message.data))
-});
+})
+
+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)

package/provider/geolonia/index.html

@@ -5,6 +5,13 @@
     <title>Charites Live Preview</title>
   </head>
   <body>
+    <div class="overlay">
+      <label><input type="checkbox" id="showTileBoundaries">show Tile Boundaries</label>
+      <br>
+      <label><input type="checkbox" id="showCollisionBoxes">show Collision Boxes</label>
+      <br>
+      <label><input type="checkbox" id="showPadding">show Padding</label>
+    </div>
     <div id="map"></div>
     <script type="text/javascript" src="https://cdn.geolonia.com/v1/embed?geolonia-api-key=YOUR-API-KEY"></script>
     <script type="text/javascript" src="/app.js"></script>

package/provider/mapbox/app.css

@@ -5,3 +5,13 @@ html, body, #map
   padding: 0;
   margin: 0;
 }
+
+.overlay {
+  width: 200px;
+  position: absolute;
+  top: 10;
+  left: 10;
+  margin: 5px;
+  z-index: 90;
+  background-color: rgba(255, 255, 255, 0.6);
+}