Merge branch 'main' into zeke-shieldlib-iife-890

.github/workflows/build-preview.yml

@@ -43,12 +43,15 @@ jobs:
         with:
           node-version: 18.16.1 #18.17.0 is buggy
       - name: Install and Build 🔧
+        # TODO: when we move shieldlib to its own repo, move shieldlib docs CI also
         run: |
           npm ci --include=dev
           npm run build
           npm run style
           npm run shields
           cp src/configs/config.aws.js src/config.js
+          mkdir -p dist/shield-docs
+          cp -r shieldlib/docs/* dist/shield-docs
       - name: Upload Build artifact
         uses: actions/upload-artifact@v3
         with:

.github/workflows/deploy-pr-checks.yml

@@ -112,7 +112,7 @@ jobs:
           " > pr_preview.md
       - uses: tibdex/github-app-token@v1
         id: checks_token
-        with: 
+        with:
           app_id: 396440 #osm-americana checks app
           private_key: ${{ secrets.CHECKS_WRITER_SECRET }}
       - name: Print Preview Links to GitHub Checks

.github/workflows/deploy.yml

@@ -25,12 +25,15 @@ jobs:
         with:
           node-version: 18.16.1 #18.17.0 is buggy
       - name: Install and Build 🔧
+        # TODO: when we move shieldlib to its own repo, move shieldlib docs CI also
         run: |
           npm ci --include=dev
           cp src/configs/config.aws.js src/config.js
           npm run build
           npm run style
           npm run shields
+          mkdir -p dist/shield-docs
+          cp -r shieldlib/docs/* dist/shield-docs
       - name: Upload 🏗
         uses: actions/upload-pages-artifact@v1
         with:

.github/workflows/test-build-mac.yml

@@ -10,9 +10,9 @@ jobs:
     steps:
       - name: Checkout 🛎️
         uses: actions/checkout@v3
-# Node v18.17.0, introduced July 18, 2023, introduces an error in unicode processing that breaks test cases on Ubuntu.
-# See PR #905 and #908 for more details.
-# If this bug is resolved in node, these lines can revert to 18.x rather than 18.16.0.
+      # Node v18.17.0, introduced July 18, 2023, introduces an error in unicode processing that breaks test cases on Ubuntu.
+      # See PR #905 and #908 for more details.
+      # If this bug is resolved in node, these lines can revert to 18.x rather than 18.16.0.
       - name: Use Node.js 18.16.1
         uses: actions/setup-node@v3
         with:

.github/workflows/test-build-ubuntu.yml

@@ -10,9 +10,9 @@ jobs:
     steps:
       - name: Checkout 🛎️
         uses: actions/checkout@v3
-# Node v18.17.0, introduced July 18, 2023, introduces an error in unicode processing that breaks test cases on Ubuntu.
-# See PR #905 and #908 for more details.
-# If this bug is resolved in node, these lines can revert to 18.x rather than 18.16.1.
+      # Node v18.17.0, introduced July 18, 2023, introduces an error in unicode processing that breaks test cases on Ubuntu.
+      # See PR #905 and #908 for more details.
+      # If this bug is resolved in node, these lines can revert to 18.x rather than 18.16.1.
       - name: Use Node.js 18.16.1
         uses: actions/setup-node@v3
         with:

.gitignore

@@ -7,3 +7,4 @@ config.js
 dist
 download
 local.config.js
+shieldlib/docs

package.json

@@ -11,13 +11,13 @@
     "shieldlib"
   ],
   "scripts": {
-    "build:shieldlib": "cd shieldlib && node scripts/build.js",
+    "build:shieldlib": "cd shieldlib && node scripts/build.js && npm run docs",
     "build:code": "exec ts-node scripts/build",
     "build": "run-s clean-build sprites build:shieldlib build:code taginfo status_map",
     "clean": "run-s clean:shieldlib clean:code clean-download clean-build",
     "clean-download": "shx rm -rf download",
     "clean-build": "shx rm -rf dist build",
-    "clean:shieldlib": "cd shieldlib && shx rm -rf dist",
+    "clean:shieldlib": "cd shieldlib && shx rm -rf dist docs",
     "clean:code": "shx rm -rf dist",
     "config": "shx cp src/configs/config.maptiler.js src/config.js",
     "code_format": "run-s code_format:prettier code_format:svgo",

shieldlib/README.md

@@ -133,8 +133,8 @@ You should create one definition entry for each network. The entry key must matc
     "drawFunc": "pentagon",
     "params": {
       "pointUp": false,
-      "offset": 5,
-      "angle": 0,
+      "yOffset": 5,
+      "sideAngle": 0,
       "fillColor": "white",
       "strokeColor": "black",
       "radius1": 2,
@@ -305,9 +305,9 @@ If `shapeBlank` is specified, the shield will be drawn as a shape. This needs to
 
 The following `params` options can be specified:
 
-- `angle` - indicates angle (in degrees) at which side edges deviate from vertical. Applies to `trapezoid`, `pentagon`, `hexagonHorizontal`, `octagonVertical`.
+- `sideAngle` - indicates angle (in degrees) at which side edges deviate from vertical. Applies to `trapezoid`, `pentagon`, `hexagonHorizontal`, `octagonVertical`.
 - `fill` - specifies the internal fill color.
-- `offset` - indicates height (in pixels) at which the bottom and/or top edges deviate from horizontal. Applies to `escutcheon`, `pentagon`, `hexagonVertical`, `octagonVertical`.
+- `yOffset` - indicates height (in pixels) at which the bottom and/or top edges deviate from horizontal. Applies to `escutcheon`, `pentagon`, `hexagonVertical`, `octagonVertical`.
 - `outline` - specifies the outline color.
 - `outlineWidth` - specifies the width of the outline.
 - `pointUp` - applies to several shape types and specifies whether the pointy side is up.
@@ -319,3 +319,7 @@ The following `params` options can be specified:
 ### Custom shield graphics
 
 In addition to the stock drawing functions, a custom draw function can be specified. `paDot` and `branson` are included as examples of this, for rendering the [Allegheny County belt system](https://en.wikipedia.org/wiki/Allegheny_County_belt_system) and the Branson, Missouri colored route system. See the file `src/custom_shields.mjs` for an example of how this is done.
+
+## Documentation
+
+See [TypeDoc generated documentation](https://zelonewolf.github.io/openstreetmap-americana/shield-docs/index.html) for detailed API information.

shieldlib/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@americana/maplibre-shield-generator",
   "description": "Generate highway shields for maplibre-gl-js maps",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "author": "OpenStreetMap Americana Contributors",
   "type": "module",
   "keywords": [
@@ -24,21 +24,24 @@
   "source": "src/index.ts",
   "devDependencies": {
     "@types/color-rgba": "^2.1.0",
+    "canvas": "^2.11.2",
     "esbuild": "^0.17.10",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.8.4",
     "shx": "^0.3.4",
     "ts-mocha": "^10.0.0",
     "ts-node": "^10.9.1",
+    "typedoc": "^0.24.8",
     "typescript": "^4.9.5"
   },
   "scripts": {
     "code_format": "run-s code_format:prettier",
     "code_format:prettier": "prettier --write --list-different .",
-    "clean": "shx rm -rf dist",
+    "clean": "shx rm -rf dist docs",
+    "docs": "npx typedoc src/index.ts",
     "test": "npm exec -- ts-mocha",
     "build:code": "node scripts/build.js",
-    "build": "run-s clean build:code",
+    "build": "run-s clean build:code docs",
     "preversion": "npm version --no-git-tag-version --preid alpha",
     "publish-alpha": "npm publish --access=public --tag alpha"
   },
@@ -59,5 +62,10 @@
   ],
   "directories": {
     "test": "test"
-  }
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "README.md"
+  ]
 }

shieldlib/src/custom_shields.mjs → shieldlib/src/custom_shields.ts

@@ -1,9 +1,15 @@
 "use strict";
 
-import * as ShieldDraw from "./shield_canvas_draw.mjs";
+import * as ShieldDraw from "./shield_canvas_draw";
+import { ShieldRenderingContext } from "./shield_renderer";
+import { ShapeBlankParams } from "./types";
 
 // Special case for Allegheny, PA Belt System
-export function paBelt(r, ctx, params) {
+export function paBelt(
+  r: ShieldRenderingContext,
+  ctx: CanvasRenderingContext2D,
+  params: ShapeBlankParams
+) {
   ShieldDraw.roundedRectangle(r, ctx, {
     fillColor: "white",
     strokeColor: "black",
@@ -36,7 +42,11 @@ export function paBelt(r, ctx, params) {
 }
 
 // Special case for Branson color-coded routes
-export function bransonRoute(r, ctx, params) {
+export function bransonRoute(
+  r: ShieldRenderingContext,
+  ctx: CanvasRenderingContext2D,
+  params: ShapeBlankParams
+) {
   ShieldDraw.roundedRectangle(r, ctx, {
     fillColor: "#006747",
     strokeColor: "white",

shieldlib/src/index.d.ts

@@ -1,14 +1,10 @@
-export {
-  Bounds,
-  GfxFactory,
-  RouteDefinition,
-  ShieldSpecification,
-  SpriteRepository,
-} from "./types";
+export * from "./types";
 export { transposeImageData } from "./screen_gfx";
 export {
   URLShieldRenderer,
   ShieldRenderer,
   InMemorySpriteRepository,
+  AbstractShieldRenderer,
 } from "./shield_renderer";
 export { getDOMPixelRatio } from "./document_graphics";
+export * from "./shield_helper";