ben-eb / css-values

Validate CSS property value pairs.

Validate CSS property value pairs.

This project is in very early alpha stages. At present, around half of the existing CSS specification is covered in a very limited capacity. Please feel free to improve the functionality of this module, and test it out, but don't yet rely on it in production!

The aim of this project is to produce a module that can consume CSS property/value pairs and validate them based on the actual CSS specification. This is useful because it brings what is traditionally hidden away in online documentation to automated tools such as linters. Indeed, with this data we can cover all of these use cases (and others):

• Remove invalid declarations which would be dropped by the browser.
• Lint properties to ensure correct syntax was being used.
• Enable text editor autocomplete for CSS values.
• Compute the Levenshtein distance between valid/invalid property values (did you mean yellow? you entered yrllow).
• Automatically generate a skeleton W3C specification document based on grammar.

css-values uses specification data gathered from Mozilla, with some overrides that make it easier for the parser to operate smoothly. In addition, css-values uses Autoprefixer to supplement values from the spec with proprietary browser syntax. This is to ensure that css-values can let these values pass through as valid, even though they are not to specification.

Property support

We support 254 of 361 CSS properties (70.36%).

• -ms-overflow-style
• -moz-appearance
• -moz-binding
• -moz-float-edge
• -moz-force-broken-image-icon
• -moz-orient
• -moz-stack-sizing
• -moz-text-blink
• -moz-user-focus
• -moz-user-input
• -moz-user-modify
• -moz-window-shadow
• -webkit-border-before-color
• -webkit-border-before-style
• -webkit-border-before-width
• -webkit-clip-path
• -webkit-mask-attachment
• -webkit-mask-composite
• -webkit-mask-position
• -webkit-mask-repeat
• -webkit-mask-repeat-x
• -webkit-mask-repeat-y
• -webkit-tap-highlight-color
• -webkit-text-fill-color
• -webkit-text-stroke-color
• -webkit-text-stroke-width
• -webkit-touch-callout
• align-content
• align-items
• align-self
• all
• animation-delay
• animation-direction
• animation-duration
• animation-fill-mode
• animation-name
• animation-play-state
• animation-timing-function
• animation-iteration-count
• appearance
• backdrop-filter
• background-blend-mode
• backface-visibility
• background-attachment
• background-color
• background-clip
• background-image
• background-origin
• background-position
• background-repeat
• background-size
• border-block-end-color
• border-block-end-style
• border-block-end-width
• border-bottom-left-radius
• border-bottom-right-radius
• border-block-start-color
• border-block-start-style
• border-block-start-width
• border-bottom-color
• border-bottom-style
• border-bottom-width
• border-collapse
• border-color
• border-image-source
• border-inline-end-color
• border-inline-end-style
• border-inline-end-width
• border-inline-start-color
• border-inline-start-style
• border-inline-start-width
• border-left-color
• border-left-style
• border-left-width
• border-right-color
• border-right-style
• border-right-width
• border-style
• border-top-color
• border-top-left-radius
• border-top-right-radius
• border-top-style
• border-top-width
• border-width
• bottom
• box-align
• box-decoration-break
• box-direction
• box-flex
• box-flex-group
• box-lines
• box-ordinal-group
• box-orient
• box-pack
• box-sizing
• box-suppress
• break-after
• break-before
• break-inside
• caption-side
• clear
• clip-path
• color
• column-count
• column-fill
• column-gap
• column-rule-color
• column-rule-style
• column-rule-width
• column-span
• column-width
• direction
• display
• display-inside
• display-list
• display-outside
• empty-cells
• filter
• flex-direction
• flex-grow
• flex-shrink
• flex-wrap
• float
• font-kerning
• font-language-override
• font-size
• font-size-adjust
• font-stretch
• font-style
• font-variant-caps
• font-variant-position
• font-weight
• grid-auto-columns
• grid-auto-rows
• grid-column-gap
• grid-row-gap
• grid-template-areas
• hyphens
• image-rendering
• ime-mode
• initial-letter-align
• isolation
• justify-content
• left
• letter-spacing
• line-break
• line-height
• list-style-image
• list-style-position
• list-style-type
• mask-image
• margin-block-end
• margin-block-start
• margin-bottom
• margin-inline-end
• margin-inline-start
• margin-left
• margin-right
• margin-top
• marker-offset
• mask-composite
• mask-mode
• mask-origin
• mask-position
• mask-repeat
• mask-size
• mask-type
• max-block-size
• max-height
• max-inline-size
• max-width
• min-block-size
• min-height
• min-inline-size
• min-width
• mix-blend-mode
• motion-offset
• object-fit
• object-position
• offset-block-end
• offset-block-start
• offset-inline-end
• offset-inline-start
• opacity
• order
• orphans
• outline-color
• outline-offset
• outline-style
• outline-width
• overflow
• overflow-clip-box
• overflow-wrap
• overflow-x
• overflow-y
• padding-block-end
• padding-block-start
• padding-bottom
• padding-inline-end
• padding-inline-start
• padding-left
• padding-right
• padding-top
• page-break-after
• page-break-before
• page-break-inside
• perspective
• perspective-origin
• pointer-events
• position
• resize
• right
• ruby-align
• ruby-merge
• ruby-position
• scroll-behavior
• scroll-snap-coordinate
• scroll-snap-destination
• scroll-snap-type
• scroll-snap-type-x
• scroll-snap-type-y
• shape-image-threshold
• shape-margin
• tab-size
• table-layout
• text-align
• text-align-last
• text-decoration-color
• text-decoration-style
• text-emphasis-color
• text-orientation
• text-rendering
• text-shadow
• text-size-adjust
• text-transform
• top
• transform
• transform-box
• transform-style
• transition-delay
• transition-duration
• transition-timing-function
• unicode-bidi
• user-select
• vertical-align
• visibility
• white-space
• widows
• will-change
• word-break
• word-spacing
• word-wrap
• writing-mode
• z-index

Contributors

Thanks goes to these wonderful people (emoji key):

Ben Briggs 💻 📖 👀 ⚠️	Ivan Serniaev 💻 ⚠️	Oleg-docent 💻 ⚠️

🎨 Logo design by Arina Efremova.

This project follows the all-contributors specification. Contributions of any kind welcome!

License

Template:CSSData by Mozilla Contributors is licensed under CC-BY-SA 2.5.

MIT © Ben Briggs

css-values's Issues

Looking for collaborators

Any contributions are welcome, as this is such a big project I don't feel like I can handle it all by myself. Indeed, currently we have nearly 4000 tests that are generated for the output module!

These contributions can be (but are not limited to) tests (passing/failing), improving the code coverage, documentation of current code (perhaps we should look into some automated documentation?), features, bug fixes, advice for implementing more properties, or helping me tackle anything that is labelled 'help wanted'.

I'm open to adding collaborators directly to the repository if I already know you, or after a first pull request if I don't. 😄

Implement property specific validation messages

Now that 0.1.0 is out, I'd like to implement more specific validation messages. These should offer more insight into why the validator might yield a warning; here are some examples:

• isColor: rgb(255, 255, 255, 1) - too many arguments, expected 3.
• isColor: rgb(255, 255) - too few arguments, expected 3.
• isColor: rgb(255, 255, 255,) - unexpected trailing comma.
• isColor: rgb(255 255 255) - expected arguments to be comma-separated.

Essentially what we have to do now is to break down the return conditions of the custom validators. Take isLength as an example. The return condition should be extracted into individual conditions that yield a message if the condition is failing. So, for example, the function checks that the value does not end with . - instead of a boolean test, we can return a message here instead:

if (!endsWith(int.number, '.')) {
  return {
    type: 'invalid',
    message: 'At least one number should follow the decimal point.',
  };
}

Suggestions for types of messages to return would be very welcome, as well as pull requests that implement these new messages. 😄

Handle global values appropriately

Currently, the output module will not handle initial, inherit or unset, the global keywords that are not defined in the specification grammar for each property. I think this is appropriate to handle globally and not per-validator; I did read somewhere that there were a couple of exceptions but I can't find the link to that now.

100% code coverage

Currently we're on ~82% covered, would be great to get that to 100%.

Outstanding syntaxes needing validators

• clip-path: <clip-source> | [ <basic-shape> || <geometry-box> ] | none
• grid-auto-columns: <track-size>
• grid-column-end: <grid-line>
• grid-template-columns: none | <track-list> | <auto-track-list> | subgrid <line-name-list>?
• mask-image: <mask-reference>#
• shape-outside: none | <shape-box> || <basic-shape> | <image>
• transition-property: none | <single-transition-property># (MDN has this as IDENT which I take to mean using isCustomIdent)

Add isBlendMode utility.

We need to be able to validate any given blend mode. This will enable us to check the following CSS properties:

• background-blend-mode
• mix-blend-mode

We can do this by creating a helper function in the validators folder named isBlendMode.js. If you need an implementation reference, you can use https://github.com/ben-eb/css-values/blob/master/src/validators/isGenericFamily.js. All we need to do here is to reference the blending modes instead! You can find the list here: https://developer.mozilla.org/en-US/docs/Web/CSS/blend-mode

Don't forget to add isBlendMode to the index of validators, located at https://github.com/ben-eb/css-values/blob/master/src/validators/index.js.

Next, we need some way to tell css-values how to generate tests for these values. You can basically follow the existing format in https://github.com/ben-eb/css-values/blob/master/src/fixtures.js - import the list of blend modes and export an object named blendMode with those as valid values, and some made up invalid value.

We then need to add this to the tests. You can do this by updating https://github.com/ben-eb/css-values/blob/master/src/__tests__/validators.js with the isBlendMode validator that you created, named blendMode. If you run the tests now with npm test you will see that blend modes are validated properly.

Hopefully if everything worked correctly, css-values will now output a file that validates the properties listed above. You can check that it does by running npm run prepublish && npm run generate. There should be a new file in output/properties/compositingAndBlending. If this worked, then please add the properties to https://github.com/ben-eb/css-values/blob/master/src/completed.js.

If you're stuck, please post here and I'll help out in any way that I can. And with that being said, PRs welcome! 😃

Template:CSSData link is broken?

The docs and code reference this URL:
https://developer.mozilla.org/en-US/docs/Template:CSSData

However this page just gives me Not Found?

Cover 100% of properties & values accurately

Need to improve parsing & the code generator to be able to handle the more complex grammars, such as <color>.

Support `scrollbar-color` property

For usage in stylelint-declaration-strict-value

API design

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. 😄

Pull in Latest Data from MDN

The data.json has not been updated in a while. Would be good to acquire the latest data from MDN.

Function validators

There is a bunch of css functions that don't have appropriate validator yet. This issue is created in order to keep track of progress in this kind of functionality.

• calc
• clip-path
• cross-fade
• element
• filter
• minmax
• transform
• attr
• gradient (proprietary support currently outstanding)

Feel free to update this post (or point out missing functions)

Integration with stylelint.

This follows on some thoughts I had in the stylelint chat.

/cc @stylelint/core

So, I believe that the primary use case for this project is to provide meaningful feedback to a developer about incorrect CSS, and so stylelint is the best fit for it. Of course, I have my own use case of being able to check validity of CSS properties before merging, but primarily I think stylelint benefits the most from this work. With this in mind, I think we need to discuss how we can integrate this into stylelint!

I am now thinking of not exposing any of the templating/generation that we do in the background, it's just not necessary for the two main use cases that I've outlined (and, it took me a while to see @davidtheclark's logic for not doing this). Instead, css-values will exist as a module on npm which you can require, and won't do any CSS parsing beyond using postcss-value-parser; you will be able to use it to return a warning message or true if the value passed validation.

import cssValues from 'css-values';

/**
 * @param {string} Property to validate
 * @param {string|valueParser} Value to validate
 */
const valid = cssValues('color', 'blue');
// => true

const invalid = cssValues('color', 'yrllow');
// => {message: '"yrllow" is not a valid value for "color".'}

To facilitate this I think we need to move to a monorepo which houses:

• The css-values module itself;
• A stylelint plugin which wraps the css-values functionality;
• A PostCSS plugin which wraps the css-values functionality;
• https://github.com/ben-eb/postcss-reduce-initial (a spin-off project which uses the same data);
• and any future module which depends on code/tests from this project.

One of the areas that I've already identified as needing improvements is the lack of feedback from the module on an invalid value. It seems like something that can be addressed fairly easily by changing the return value (in the invalid case) of a lot of the different validator functions. So, if you'd like to contribute then this is a really good way to do so!

Please let me know if you have any questions/suggestions/feedback, it really helps! 😄

next validator task

Hi, Ben! I want next validator task)

Consolidate identical validators

Simple example; padding-left is the same as padding-top is the same as padding-right is the same as padding-bottom. There should be a way of merging validators which have the same configuration, greatly simplifying an output module.

We could probably do this by storing the data in memory instead of writing to disk straight away. Once all property/value pairs are parsed and merged, we could then write the files.

Support proprietary gradient syntaxes.

body {
  background: -moz-linear-gradient(top, #1e5799 0%, #2989d8 50%, #207cca 51%, #7db9e8 100%); /* FF3.6-15 */
  background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#1e5799), color-stop(50%,#2989d8), color-stop(51%,#207cca), color-stop(100%,#7db9e8)); /* Chrome4-9,Safari4-5 */
  background: -webkit-linear-gradient(top, #1e5799 0%,#2989d8 50%,#207cca 51%,#7db9e8 100%); /* Chrome10-25,Safari5.1-6 */
  background: -o-linear-gradient(top, #1e5799 0%,#2989d8 50%,#207cca 51%,#7db9e8 100%); /* Opera 11.10-11.50 */
  background: -ms-linear-gradient(top, #1e5799 0%,#2989d8 50%,#207cca 51%,#7db9e8 100%); /* IE10 preview */
  background: linear-gradient(to bottom, #1e5799 0%,#2989d8 50%,#207cca 51%,#7db9e8 100%); /* W3C, IE10+, FF16+, Chrome26+, Opera12+, Safari7+ */
}

http://www.colorzilla.com/gradient-editor/ is a good tool to use for generating the backwards compatible syntaxes.

Handle multiple values appropriately

At the moment, this module just validates a single value and doesn't handle multiple values very well. For example, in the output module a couple of tests for the initial-letter property are failing, because the module doesn't take into account the position of each of the values.

normal | [<number> <integer>?]

https://developer.mozilla.org/en-US/docs/Web/CSS/initial-letter

So, we need to make the module aware of multiple value syntaxes such as this one; test fixtures should be generated to handle cases such as initial-letter: 3.0 2 for example.