Refactor project to allow use as a dependency

[adamfranco]

This project has started pretty organically and now that #137 is getting close, it may be time to think about refactoring the code for clarity for contributors.

Broadly, there are two ways that this project can be used:

1. As a stand-alone map rendering/demo.
2. As a dependency of another map, a style that another application would want to use as a basemap or to render its data.

The stand-alone map/demo case is currently what we've been focused on, but the inclusion of the style as a dependency of other projects shouldn't be too far off.

Here are some steps that might get us there, though I'm probably missing a few and these should be discussed:

1. Move package.json to the root of the repository if there isn't a good reason to bury it in style/.
2. Move index.html out of the style/ directory either to the root or to a demo/ or site/ subdirectory.
3. Move the config and maplibre calls out of americana.js into an index.js or demo.js that goes with the demo's index.html. This should leave americana.js exporting a style object with all layers that is as complete as possible and which can be passed added in the demo or other map renderings after having the source tweaked to add the access key or change the source url.
4. Any dependencies for the demo should be included when running npm i --include=dev. Any dependencies that are needed only when used as a library should be included by default.
5. If the style needs to distribute built artifacts for consumption by downstream users, these should be added as addition tasks and packaged as releases.

Thoughts? What did I miss?

I think this is blocked by #137, but I could be wrong.

[ZeLonewolf]

See also #104, #70

[ZeLonewolf]

Not mentioned is also a dev folder, which I envision could be a collection of useful developer files and utilities, such as the Inkscape color palette file envisioned by #133 or perhaps @jleedev 's shield generator.

[adamfranco]

If any useful developer tools don't specifically rely on the style or vice-versa then another would be to factor them out into their own repositories and include them as --save-dev npm dependencies. This would let them be used in other projects without this whole style coming along for the ride. This might not apply to these tools, but was what I had in mind for OpenMapSamples & OpenMapSamples-Maplibre -- they are very much built to support of this project, but can also be used in other styles and map rendering projects.

[ZeLonewolf]

I agree with that approach. I'm thinking specifically of dev tools that are specific to this style.

[zekefarwell]

Because it works via the styleimagemissing event, the shield rendering code is more of a MapLibre extension than a part of the style itself. I think this means that another project offering multiple maps with a style picker would get shields rendered regardless of the currently active style. Not sure if there is a way to avoid this, but something to consider if we are going to work on making Americana usable within other projects.

[ZeLonewolf]

I think this means that another project offering multiple maps with a style picker would get shields rendered regardless of the currently active style. Not sure if there is a way to avoid this, but something to consider if we are going to work on making Americana usable within other projects.

Well, the map object would either need to get destroyed and recreated or its properties updated. Really this just means we add recycling the styleimageimssing event hook along with everything else that parameterizes the maplibre map object to the list of things that need to be swapped when style swapping. I would personally not worry about those mechanics until we encounter a specific use case for how to switch styles on the fly like that.

[zekefarwell]

I guess the first use case I imagined for adding Americana as a dependency of another project was an existing MapLibre app offering multiple styles wanting to add Americana as an option. Maybe there are other use cases I'm not thinking of though. I'd expect most projects would be using a Mapbox gl plugin for style switching like one of these:
https://github.com/korywka/mapbox-gl-controls
https://github.com/el/style-switcher
Anyway, it's not something we need to worrry about. I'm just expecting it's something people will start asking for if we say "Americana can now be pulled in as a dependency for your project".

[ZeLonewolf]

In terms of dependencies, the use case I'm thinking of is "I want to embed an Americana map on my site and use it as a base layer" So that user would desire to take the generated style JSON, a .js file that draws the shields, and the shield blanks as input. Then they could do whatever with the map object from there.

[clementmas]

I'd love to be able to provide the OSM Americana style to the users of TravelMap (to trace roadtrip itineraries across the US) but I'm wary of the added code complexity and the maintenance burden for a single style.
At the moment I simply have to pull a JSON style for each map style provided.

How much JS would need to be pulled-in to add the OSM Americana style? Would it be a simple npm package that needs to be added as a dependency?