stamen / mapbox-gl-style-build Goto Github PK

We've done a few releases with new features or bug fixes here: https://github.com/stamen/mapbox-gl-style-build/releases

We should start a changelog for this repo. Let's backfill it with any information in the release notes.

Followup to #17

Looks like we are pulling the style name we are using for logging warnings from the directory containing the style since the build system has a pattern of building styles to style-name/style.json.

Unfortunately, this doesn't account for nesting of directories which is valid so if a style is in, for example, cool-style/light/style.json the warning will tell you to look at the light style as opposed to cool-style light.

We could either use the entire path to the style json or try to rely on style name or id here.

Acceptance criteria

• Users have a better indicator of which style is producing a validation error and where to find the style

I just went to use the new create-layer-templates script on a repo and ran into issues around layer id capitalization. This produced unexpected results where inconsistent capitalization across otherwise identical ids in styles failed equality checks to signal the same layer id was found but still overwrote outputted layer js files. I resolved this by changing all style layer ids to lower case in those styles and rerunning the script, but because the root cause was hard to pick out, we should have some handling in the script itself for these scenarios.

Capitalizing layer ids is never best practice, but we could account for this by forcing all style layers to lower case before breaking the layers out and comparing them to each other by style id. We should warn in the console when we do this.

Currently we say "Couldn't load ... does it exist?" But this error will also get thrown when there is a JS error (eg, that style tries to load a module that doesn't exist).

It would be great to be more descriptive here and possibly show a stack trace with a verbose option.

Up to now we have gotten away with only merging styles once in the build system (by exporting baseStyle and overrides objects from layers). But there are situations where a layer author may want to merge multiple sets of overrides and export one set of overrides.

Current thinking would be that we expose a mergeOverrides function that layer authors could use, like this:

[...]

let overrides = {};

if (context.transparency === 'clear') {
  overrides = mergeOverrides(overrides, {
    paint: {
      'line-opacity': context.clearOpacity
    }
  });
}

if (context.palette === 'dark') {
  overrides = mergeOverrides(overrides, {
    paint: { 'line-color': context.darkRoadColor }
  });
}

We currently have mergeVariables and extend, maybe we could unify these and export that function with a mergeOverrides alias? The thinking here is that it would make the usage of that function more explicit in layers, but it would also keep us open in case down the line we decide we want to do something differently when merging overrides--the interface would remain the same.

Currently there is no automated way to find unused variables, it would be handy to have one.

One way to go about this would be a command line tool that tracks all variables provided and reports back on which don't get used by any of the template styles.

This might be part of a more complete linting tool that would check for other issues such as variables used in templates that aren't defined.

Describe the issue

The build system currently allows you to set up variables that can be used across variants. It would be helpful to support math modifiers for these variables to avoid duplicating work.

For example, I have a variable file with text size expressions for one set of variants. For another set of variants, I want the text to be larger overall, but adjustable for each variable (some *1.5 and some *2, for example) without needing to rewrite the original expression completely.

Some variables can be missing without causing any errors in the stylesheet build. I know that there are some warnings in place, because deleting some color variables does cause warnings. I'm not sure why these are not being caught.

Right now, the build system expects a fairly rigid structure for your files:

// template files
- templates
    - layers
        - ...
    - styles
        - style-template-1.js
        - style-template-2.js

// built files
- styles
    - style-1.json
    - style-2.json

In this structure, the style templates exist at only one flat level inside of a styles (or otherwise named) directory and will output to a similarly structured directory. They cannot nest deeper inside of more directories used for organization inside of this.

We want to allow for different directory structures for any amount of nesting that a user wants where the built directory structure will reflect the structure of the template files directory. For example:

// template files
- templates
    - layers
        - ...
    - styles
        - category-a
            - style-template-1.js
            - style-template-2.js
        - category-b
            - style-template-3.js
            - style-template-4.js

// built files
- styles
    - category-a
        - style-1.json
        - style-2.json
    - category-b
        - style-3.json
        - style-4.json

The build system currently assumes you are building your styles to fit the system. For some projects that have already started, implementing the build system first requires choosing a style and breaking out layers into the appropriate files.

We've written scripts to do this for specific clients. We should expand on this by creating a generic helper script with this library that can be used for any pre-existing project being converted into the build system structure.