API design

[ben-eb]

One of the things that I am unsure of is how to design an appropriate API for this project, and which things that we need to expose. Currently, we have;

• Data from Mozilla, supplemented by Autoprefixer (and some manual overrides).
• A grammar parser/tokenizer.
• Templates for generating scripts for tests/validation etc.
• A tool that takes these parts and outputs a whole module.

The templates are mostly what I'm having difficulty with here. How much of this do we expose?

Discussion is open. 😄

[davidtheclark]

I wonder if maybe css-values does not have to expose its data or its parser or even its templates.

As discussed over here, I wonder if users will only be interested in two exposed features:

• an AST representing the definitions
• functions for validating property values

I also wonder why these could not be generated and then versioned and published on their own instead of requiring users to install css-values as a devDependency and then generate their own functions.

[davidtheclark]

Question: I noticed that the output property value validation functions expect a parsed argument. Is that expected to be a value parsed by postcss-value-parser? Or something else?

[ben-eb]

property value validation functions expect a parsed argument

Yes, there is one module that consumes these property validation functions, which is generated when you run the generator. Currently it does not use PostCSS to parse real CSS, but a much simpler "parser" that takes a single declaration. This is only done for speed right now.

We could version the functions that validate property/value pairs, my concern with that is the function needed will have different requirements depending on the caller. For example simple validation is OK with the current setup, but what about a module that told you which parts of the value corresponded to what longhand property? e.g. background: url(cat.png) repeat-x could be consumed by a validator that returned something like {backgroundImage: "url(cat.png)", backgroundRepeat: "repeat-x"}. I just don't know yet as there are probably other use cases that would want different validators outputted.

[davidtheclark]

We could version the functions that validate property/value pairs, my concern with that is the function needed will have different requirements depending on the caller. For example simple validation is OK with the current setup, but what about a module that told you which parts of the value corresponded to what longhand property

I'm not sure that "depends on the caller." Isn't it true that you can't validate background unless you determine which parts of the value apply to which longhand property, and then validate each part against its corresponding property? So the output functions need to be able to do that, right? — if their intention is to validate all property value pairs?

[davidtheclark]

My concern here is that the suggested usage is quite unusual (i.e. that you run css-values in order to output validation functions and a value definition AST into your own project that should be packaged and versioned with your project). Is there precedent for this pattern that I'm not aware of?

I guess what I'm saying is that if the validation functions work and the AST is accurate, aren't those all anybody needs?

[ben-eb]

https://en.wikipedia.org/wiki/Metaprogramming

[ben-eb]

Yes, if someone were to use this tool to generate property validators that could inspect shorthand like the example, the output functions would need to do that. This is why I think it would be good to expose this templating. 😄

[davidtheclark]

This is why I think it would be good to expose this templating.

I don't understand. Don't we want instead to improve the existing templates so that they do address shorthand properties?

[ben-eb]

Yeah, we want to improve the existing templates. Perhaps we should just start with that and go from there? I don't mind shipping code where people don't have to use a generator, and like you say it's more complex than other things that you might install from npm. Once we can get parsing finished we could revisit other templating, if it comes up.

What do you think?

[just-be-dev]

Are you going to set up a separate project for the actual generated project or is it going to be all bundled together?

[ben-eb]

@zephraph I'm not sure exactly how we want to do this. We could do either of these:

• What we have now; a module that will be able to generate CSS validators, where a user will have to produce a template to output a whole module.
• A babel style monorepo, where we contain all generated modules in one place. So whomever is working on our "core team" will be working on all modules at once. This might be a bit better in the long run, as things like tests can be consolidated together.

I'm sorry for missing your question.