Merge branch 'main' into shields-south-africa

.gitattributes

@@ -0,0 +1 @@
+* text=auto

.github/workflows/deploy.yml

@@ -5,23 +5,32 @@ on:
   push:
     branches:
       - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
 jobs:
   build-and-deploy:
     runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v2.3.1
+        uses: actions/checkout@v3
       - name: Use Node.js 17.x
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v3
         with:
           node-version: 17.x
       - name: Install and Build 🔧
         run: |
           npm ci --include=dev
           cp src/configs/config.aws.js src/config.js
           npm run build
-      - name: Deploy 🚀
-        uses: JamesIves/github-pages-[email protected]
+      - name: Upload 🏗
+        uses: actions/upload-pages-artifact@v1
         with:
-          branch: gh-pages # The branch the action should deploy to.
-          folder: dist/ # The folder the action should deploy.
+          path: ./dist
+      - name: Deploy 🚀
+        id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/lint.yml

@@ -10,7 +10,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           # Make sure the actual branch is checked out when running on pull requests
           repository: ${{ github.event.pull_request.head.repo.full_name }}

.github/workflows/test-build.yml

@@ -9,9 +9,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v2.3.1
+        uses: actions/checkout@v3
       - name: Use Node.js 17.x
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v3
         with:
           node-version: 17.x
       - name: Install and Build 🔧
@@ -20,3 +20,6 @@ jobs:
           sed 's/<your MapTiler key>/53iZvB2drcamS0Ge0xiD/g' src/configs/config.maptiler.js > src/config.js
           npm run build
         # MapTiler key 53iZvB2drcamS0Ge0xiD only allows requests from zelonewolf.github.io
+      - name: Test 🧪
+        run: |
+          npm test

.mocharc.yml

@@ -0,0 +1 @@
+recursive: true

.prettierignore

@@ -2,3 +2,4 @@ build
 sprites
 js/maplibre-gl.js
 dist
+.pnp.*

ACKNOWLEDGEMENTS.md

@@ -1,4 +1,6 @@
 # Thanks
 
-- The stylized highway shields are inspired by "rebusurance" by Minh Nguyễn (https://github.com/1ec5/rebusurance)
-- Initial layer code is derived from Oliver Wipfli's openmaptiles-starter style: https://github.com/wipfli/openmaptiles-starter
+- The stylized highway shields are inspired by "[Rebusurance](https://github.com/1ec5/rebusurance/)" by Minh Nguyễn.
+- Initial layer code is derived from Oliver Wipfli's [openmaptiles-starter](https://github.com/wipfli/openmaptiles-starter/) style.
+- The font stack was [packaged by the OpenHistoricalMap project](https://github.com/OpenHistoricalMap/map-styles/).
+- Support for right-to-left Arabic and Hebrew text is provided by the [mapbox-gl-rtl-text](https://github.com/mapbox/mapbox-gl-rtl-text/) plugin.

CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# Code of Conduct
+
+The OpenStreetMap Americana project has [opted in](https://github.com/ZeLonewolf/openstreetmap-americana/pull/489) to the [OpenStreetMap US Code of Conduct](https://wiki.openstreetmap.org/wiki/Foundation/Local_Chapters/United_States/Code_of_Conduct_Committee/OSM_US_Code_of_Conduct) (CoC) and [Process for Moderation](https://wiki.openstreetmap.org/wiki/Foundation/Local_Chapters/United_States/Code_of_Conduct_Committee/ModerationProcess).

CONTRIBUTING.md

@@ -4,12 +4,12 @@ _'murica!_
 
 The style is located within **src/** and is organized as follows:
 
-- **layer/** - Individual style layers, organized by subject area
+- **layer/** - Individual style layers, organized by subject area. The ordering of layers is specified in `index.js`.
 - **icons/** - SVG icons, which get converted into PNG stylesheets
 - **constants/** - Style elements that are frequently re-used
 - **js/** - Dynamic javascript code for highway shields and stylesheet building
-- **config.js** - Configuration settings (MapTiler API key, OpenMapTiles URL, etc)
-- **americana.js** - OpenMapTiles loader with layer ordering
+- **config.js** - Configuration settings (MapTiler API key, OpenMapTiles tile server URL, etc)
+- **americana.js** - MapLibre loader and configuration for the demo map
 - **index.html** - Demonstration map HTML page
 
 ## Install Node.js
@@ -43,9 +43,9 @@ It may be necessary to prefix these with `sudo` depending where NPM is installed
 
 ## Platform Specific Notes
 
-### MacOS
+### macOS
 
-MacOS doesn't include a default package manager, but Node.js and NPM can be installed via
+macOS doesn't include a default package manager, but Node.js and NPM can be installed via
 [Homebrew][50] or [MacPorts][51]:
 
 - Homebrew - `brew install node`
@@ -160,9 +160,20 @@ boilerplate in `scripts/taginfo_template.json`.
 
 1. Please prettify all files prior to submission. Run `npm run code_format` to
    format code files with [prettier][90] and SVG files with [SVGO][svgo].
-2. If you are introducing a novel approach to depicting a layer or feature
+2. If you are introducing a new kind of feature to the style, add a section to
+   `src/js/legend_config.js` or a legend entry in the corresponding file in
+   `src/layer/` that tells the Legend control how to find and render a
+   representative feature. Also try out the Samples button to catch any visual
+   conflicts.
+3. If you are introducing a novel approach to depicting a layer or feature
    property from the OpenMapTiles schema, document how the corresponding
    OpenStreetMap key or tag is used in `scripts/taginfo_template.json`.
+4. If any shield background icons are introduced, add lines to `src/shieldtest.js`
+   to demonstrate overlaid text on each of them.
+5. If you are introducing new JavaScript code that can run independently of a
+   browser environment, add automated unit tests for it to `test/spec/`, then
+   run `npm test` to ensure that they pass. This project structures unit tests
+   using [Chai](https://www.chaijs.com/guide/styles/) for assertions.
 
 [90]: https://prettier.io/
 [svgo]: https://github.com/svg/svgo/
@@ -255,7 +266,7 @@ Additionally, **`refsByWayName`** is an object mapping way names to text that ca
 
 `refsByWayName` only works if there is no `ref` tag and the expression in the `routeConcurrency` function in layer/highway_shield.js includes the `name` property in the image name. The network needs to be listed as an input value that causes the `match` expression to append `name` to the image name.
 
-When using `overrideByRef` or `refsByWayName`, make sure to add a line to the bottom section of this page explaining why it is necessary, as they are only intended for use in special cases.
+When using `overrideByRef` or `refsByWayName`, make sure to add a line to the Special Cases section of this page explaining why it is necessary, as they are only intended for use in special cases.
 
 ### Banners
 
@@ -291,6 +302,7 @@ This style strives to draw representative highway shields wherever they are tagg
 - Shields with a stacked ref configuration, with `/` separating the two lines of text in the `ref` value. Currently, these `ref` values are displayed verbatim on one line, and the code necessary for stacked ref rendering has not been written yet ([#366](https://github.com/ZeLonewolf/openstreetmap-americana/issues/366)). Such cases include:
   - **Italy "Diramazione" (branch) motorways**. Between their main autostrade "A" roads, the Italian motorway network has branch motorways which carry the name of both highways that they connect. For example, the A7 and A26 motorways have a branch motorway named A7/A26, which is correctly tagged `ref=A7/A26` and shown on shields with the two numbers stacked vertically.
   - **West Virginia County Routes**. The West Virginia Department of Transportation posts County Routes, which can have shields with two stacked numbers. For example, in Mercer County, County Route 460/1 is a branch off U.S. Route 460, and County Route 27/6 is a branch off County Route 27. These routes are correctly tagged `ref=460/1` and `ref=27/6` respectively, and shown on shields with the two numbers stacked vertically.
+- The [highway classification system of the United Kingdom](https://wiki.openstreetmap.org/wiki/Roads_in_the_United_Kingdom). In the UK, mappers need to and are able to tag the actual official road classifications independently of route networks. The color and style of route signage is based on a strict 1:1 correspondence with the `highway=*` value of the underlying road, and **not** based on M/A/B highway network type. While "M" roads are always motorways with blue route symbology, "A" roads can anything from primary through motorway, and thus may take one of three colors and may change along a single route. Even if mappers were to create route relations containing all roads with the same route number, these relations would not be usable for determining how to render route symbology. Additionally, there are no route concurrencies in the UK; all roads that are `highway=secondary` or higher carry a single `ref` value that can be directly rendered into a shield without pre-processing. There is established data consumers support for this highway classification-based symbology system, most notably OpenMapTiles, which has provided pseudo-network values for UK routes since the project's inception. Therefore, this project consumes the UK pseudo-network scheme established by OpenMapTiles and colors UK route network symbology strictly based on `highway=<motorway/trunk/primary/secondary>` consistent with UK signage.
 
 ### Shield Test Gallery
 
@@ -309,3 +321,34 @@ To test with a list of all the supported networks in the style this line can be
 https://github.com/ZeLonewolf/openstreetmap-americana/blob/581e1e5d97f5745c1bf764689439d93403888505/src/shieldtest.js#L200-L201
 
 This results in a very long page and can be quite slow or even crash the browser tab.
+
+## Points of Interest
+
+A "point of interest" or POI is any feature on the map represented by an icon on the map.
+
+### Categories
+
+POIs are broken down into the following broad categories, in order to constrain the number of colors shown on the map. Some features may not cleanly fit into one category or another. Contributors should consider other POIs in the category to determine which category is the best fit.
+
+- **Geographic Place Names**: labels associated with `place=` tags, for countries, cities, locations, etc.
+- **Infrastructure**: features associated with public infrastructure, health, safety, or government.
+- **Consumer**: businesses that provide services to the public, such as shops and restaurants.
+- **Outdoor**: parks, nature reserves, and other outdoorsy features.
+- **Attraction**: places where people go for entertainment, leisure, or curiosity.
+- **Transportation**: places where people can access forms of transportation, such as airports, train stations, bus stops, and other public transit.
+
+### Color Scheme
+
+For consistency, POI icons should use the following color palette:
+
+| Category               | Scheme          | Color                                                                       | RGB         | Hex triplet |
+| ---------------------- | --------------- | --------------------------------------------------------------------------- | ----------- | ----------- |
+| Geographic Place Names | N/A             | <img src="doc-img/black.svg" height=18 width=50 /> Black                    | 0 0 0       | #000000     |
+| Infrastructure         | Pantone 294     | <img src="doc-img/pantone_294.svg" height=18 width=50 /> Blue               | 0 63 135    | #003f87     |
+| Consumer               | UTexas Orange   | <img src="doc-img/texas_orange.svg" height=18 width=50 /> Orange            | 191 87 0    | #bf5700     |
+| Outdoor                |                 | TBD (green?)                                                                |             |             |
+| Attraction             |                 | TBD (brown?)                                                                |             |             |
+| Transportation         | Medium Purple C | <img src="doc-img/pantone_medium_purple_c.svg" height=18 width=50 /> Purple | 78 0 142    | #4e008e     |
+| Knockout               |                 | <img src="doc-img/background.svg" height=18 width=50 /> Lt Grayish Orange   | 249 245 240 | #f9f5f0     |
+
+POIs without a background fill should have a 1px border using the "knockout" color above.

README.md

@@ -1,9 +1,13 @@
-# OpenStreetMap Americana Style
+# OpenStreetMap Americana
 
 _A quintessentially American map style_ [🗺 View the map](https://zelonewolf.github.io/openstreetmap-americana/)
 
 <img src="doc-img/osm-americana-logo.png" alt="Americana map style logo" width="200"/>
 
+> _The United States of America is such a glorious mess of contradiction, such a crazy quilt of competing themes, such a fecund mishmash of people and ideas, that defining us is pretty much pointless. There is, of course, a kind of faded notion of "Americana", one that concerns Route 66, diners, freak rock formations, and the like—but even in its halcyon days this "roadside attraction" version of America was never an accurate or nuanced distillation of our massively complicated culture._ <br/><sub>-Hampton Sides, <i>[Americana: Dispatches from the New Frontier](<https://en.wikipedia.org/wiki/Americana_(book)>)</i> (2004)</sub>
+
+<br />
+
 The purpose of the Americana style is to:
 
 - Promote collaboration and common purpose in the American mapping community
@@ -12,14 +16,21 @@ The purpose of the Americana style is to:
 
 The Americana style is the first digital map to achieve concurrent, state-specific highway shields arranged along the path of road. Representative highway shield rendering is of considerable cartographic importance to the American community. We do this proudly in an open source project using vector tile technology.
 
-## Contributor's Guide
+## How to use
+
+You can install the OpenStreetMap Americana package and [deploy it anywhere](CONTRIBUTING.md#Production%20builds) as a static webpage. For your convenience, we’ve deployed it [on GitHub Pages](https://zelonewolf.github.io/openstreetmap-americana/). Click the Legend button to learn the meaning of each symbol, line, and color based on the features currently visible on the map.
+
+The style tries to label places in [your browser’s preferred language](https://www.w3.org/International/questions/qa-lang-priorities). To change this preference, consult your browser’s documentation: [Chrome](https://support.google.com/chrome/answer/173424), [Firefox](https://support.mozilla.org/en-US/kb/use-firefox-another-language), [Safari for macOS](https://support.apple.com/guide/mac-help/change-the-system-language-mh26684/mac), [Safari for iOS](https://support.apple.com/en-us/HT204031). You can also override this preference by adding `&language=` to the URL, followed by a comma-separated list of [IETF language tags](https://www.w3.org/International/articles/language-tags/). For example, here’s a map labeled [in Portuguese, falling back to Spanish](https://zelonewolf.github.io/openstreetmap-americana/#language=pt,es). If we don’t have the name of a place in any of your preferred languages, the style shows the name in the local language as a last resort.
+
+## Contributor’s guide
 
 _Contributors welcome!_
 
 The repository is organized as follows:
 
 - **src/** - The map style. See [CONTRIBUTING.md](CONTRIBUTING.md).
 - **dev/** - Development tools used for style development. See [Style Developer Tools](dev/README.md)
+- **test/** - Automated unit tests.
 - _Coming soon! Other customized parts of the tech stack._
 
 Some general guidelines:
@@ -30,19 +41,21 @@ Some general guidelines:
 - This style operates on the principle of consensus. Maintainers should ensure that changes represent a broad consensus within the American mapping community.
 - Maintainers are also responsible to ensure that this principle of consensus does not cause stagnation or inaction. Contributor time is valuable; accepting the responsibility of being a maintainer means committing to responding to issues and PRs on a reasonable timeline that encourages community participation.
 
-## Technology Stack
+## Technology stack
 
 The technology stack for this style can be summarized below:
 
 <img src="doc-img/architecture.drawio.svg" alt="Americana technology stack" />
 
-## Data Sources
+## Data sources
 
 The OpenStreetMap Americana style is built upon the [OpenMapTiles schema](https://openmaptiles.org/schema/), which includes:
 
 - Feature data from OpenStreetMap
 - Translated name labels from [Wikidata](https://www.wikidata.org/wiki/Wikidata:Main_Page) for places, POIs, airports, roads, bodies of water, parks, and mountain peaks.
-- Low-zoom ocean/water and boundary data from [Natural Earth](https://www.naturalearthdata.com/).
+- Low-zoom ocean/water, boundary, and urbanized area data from [Natural Earth](https://www.naturalearthdata.com/).
+
+The legend’s “Route markers” section is labeled using labels of Wikidata items that are tagged with the [corresponding OSM tag](https://www.wikidata.org/wiki/Property:P1282).
 
 ## Coverage
 

dev/americana.gpl

@@ -10,5 +10,6 @@ Name: americana.gpl
 196 214   0 Yellow-Green
 223  70  97 Pink
 243 143   0 Orange
+186 82    5 Consumer POI Orange
 255 205   0 Yellow
 255 255 255 White