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?

[ZeLonewolf]

@clementmas a built style.json is now available:
https://americanamap.org/style.json
However, the shield piece is not yet in a packaged state; that work is in progress in #699.

[ZeLonewolf]

@adamfranco can you revisit the intent of this issue and assess where we are versus where we would need to be in order to satisfy the intent of "allow use as a dependency"?

[adamfranco]

I think the main use case I was thinking of is as a base-map for an application. For example, let's say i want to provide a map application to render arbitrary custom data served from my own database (for example something like OpenCampingMap or Curvature has its own searching/filtering/navigation controls, and I want to add the Americana map rendering as a base layer over which my own data layers are rendering. I would also then want to be able to Assuming the application is using the Maplibre stack, it would be great to be able to add Americana as a dependency [in a node-based project's package.json] and then add the Americana map layers in one go. Being able to optionally add the legend control would be nice, but it might conflict with some use-cases.

I think I'd need to do some more testing to see how close we're getting to meeting this use-case -- maybe we're already there, maybe not.

[neodescis]

I find myself here while trying to figure out the best way to add shields to my own map base style(s). I see that the shield generator has been published as its own package, which is great, but are there plans to do so for the shield definitions (and associated icons) as well? I'd love to leverage what you all have been building here!

[ZeLonewolf]

The sprites and shield definitions are published but they're probably not documented.

Shield definitions: https://americanamap.org/shields.json
Sprites base location: https://americanamap.org/sprites/ (for example, the 1x sprite sheet)

[neodescis]

Thank you for that, but it seems those files are not part of what's published in the openstreetmap-americana npm package. Am I missing something? I suppose I can run the build scripts in there myself if I have to, but it'd be nice to have shields.json and the sprites as something I could install with npm.

[ZeLonewolf]

Thank you for that, but it seems those files are not part of what's published in the openstreetmap-americana npm package. Am I missing something? I suppose I can run the build scripts in there myself if I have to, but it'd be nice to have shields.json and the sprites as something I could install with npm.

The openstreetmap-americana npm package was published in error, probably when I was learning how to publish to npm. I've unpublished it since it definitely wasn't ready for prime time. At this point, the only npm package deliberately published is the shield library, published under the name @americana/maplibre-shield-generator. Sorry about that!

That said, I would welcome a better understanding about how end users would want to be able to deploy the style and explore those use cases. We are in the process of slowly breaking up the monorepo into separate repositories, with the shield library being the first of these.

[neodescis]

From my perspective, I would really like to use the shield generator and the shield mappings, hopefully with the protomaps basemap vector tiles. I realize that the mappings are tightly coupled to the tile data, but I've filed an issue there to hopefully get their shield data into a state that it will be compatible. I might or might not use the Americana shield images directly, as I may want an SDF version, etc. Actually, it would be awesome if Americana provided SDF sprites too!