Merge pull request #916 from ZeLonewolf/zlw-move-shield-helpers

Move shield definition helper functions to shield library

.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.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:

.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

@@ -127,8 +127,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,
@@ -299,9 +299,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.
@@ -313,3 +313,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": [
@@ -19,21 +19,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"
   },
@@ -51,5 +54,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";

shieldlib/src/index.ts

@@ -1,17 +1,13 @@
-export {
-  Bounds,
-  GraphicsFactory,
-  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";

shieldlib/src/screen_gfx.ts

@@ -3,7 +3,7 @@ import { StyleImage } from "maplibre-gl";
 import rgba from "color-rgba";
 
 const defaultFontFamily = '"sans-serif-condensed", "Arial Narrow", sans-serif';
-export const shieldFont = (size: string, fontFamily: string) =>
+export const shieldFont = (size: number, fontFamily: string) =>
   `bold ${size}px ${fontFamily || defaultFontFamily}`;
 export const fontSizeThreshold = 12;
 

shieldlib/src/shield.d.ts

@@ -14,7 +14,8 @@ export function storeNoShield(
 
 export function missingIconLoader(
   renderContext: ShieldRenderingContext,
-  routeDef: RouteDefinition
+  routeDef: RouteDefinition,
+  spriteID: string
 ): void;
 
 export function romanizeRef(ref: string): string;