Add matches for CSS features

[Elchi3]

In #3631 we've added matches objects to the schema.

Both webhint.io and https://github.com/eduardoboucas/compat-report (and probably other BCD data consumers) need matches objects to analyze compatibility of CSS features.

In eduardoboucas/compat-report#4 @eduardoboucas lists features for which we should have a matches object ("transforms" in his project). I'm opening this issues to track work for adding matches to all of the CSS features that need them.

I don't know how to prioritize these yet. This is the current list:

• animation-direction

  • reverse
  • alternate-reverse

• background-attachment

  • multiple_backgrounds
  • local

• background-clip

  • content-box
  • text

• background-color

  • alpha_ch_for_hex

• background-image

  • multiple_backgrounds
  • gradients
  • svg_images
  • element
  • image-rect
  • any_image

• background-origin

  • content-box

• background-position-x

  • two_value_syntax

• background-position-y

  • 2_value_syntax

• background-position

  • multiple_backgrounds
  • 4_value_syntax

• background-repeat

  • multiple_backgrounds
  • 2-value
  • round_space

• background-size

  • contain_and_cover
  • SVG_image_as_background

• background

  • multiple_backgrounds
  • SVG_image_as_background
  • background-size
  • background-origin
  • background-clip

• border-bottom-left-radius

  • percentages
  • ellipitcal_corners

• border-bottom-right-radius

  • percentages
  • ellipitcal_corners

• border-image-repeat

  • round
  • space

• border-image

  • optional_border_image_slice
  • fill_keyword
  • gradient

• border-radius

  • elliptical_borders
  • 4_values_for_4_corners
  • percentages

• border-top-left-radius

  • percentages
  • ellipitcal_corners

• border-top-right-radius

  • percentages
  • ellipitcal_corners

• clear

  • flow_relative_values

• column-count

  • on_display_table_caption

• column-width

  • intrinsic_sizes
  • on_display_table_caption

• columns

  • on_display_table_caption

• flex-basis

  • auto
  • content

• flex-grow

  • less_than_zero_animate

• float

  • flow_relative_values

• font-family

  • system_ui

• font-size

  • rem_values

• font-variant-alternates

  • annotation
  • character_variant
  • ornaments
  • styleset
  • stylistic
  • swash

• font-variant

  • uppercase_eszett
  • turkic_is
  • greek_accented_characters
  • css_fonts_shorthand

• font

  • system_fonts
  • font_stretch_support

• grid-gap

  • percentage_values

• grid-template-columns

  • minmax
  • repeat

• grid-template-rows

  • minmax
  • repeat

• list-style-type

  • arabic-indic
  • armenian
  • bengali
  • cjk-decimal
  • cjk-earthly-branch
  • cjk-heavenly-stem
  • cjk-ideographic
  • decimal-leading-zero
  • devanagari
  • disclosure-closed
  • disclosure-open
  • ethiopic-numeric
  • georgian
  • gujarati
  • gurmukhi
  • hebrew
  • hiragana
  • hiragana-iroha
  • japanese-formal
  • japanese-informal
  • kannada
  • katakana
  • katakana-iroha
  • khmer
  • korean-hangul-formal
  • korean-hanja-formal
  • korean-hanja-informal
  • lao
  • lower-greek
  • lower-latin
  • malayalam
  • mongolian
  • myanmar
  • oriya
  • persian
  • simp-chinese-formal
  • simp-chinese-informal
  • tamil
  • telugu
  • thai
  • trad-chinese-formal
  • trad-chinese-informal
  • upper-latin
  • string
  • symbols

• list-style

  • symbols

• margin-bottom

  • auto

• margin-left

  • auto

• margin-right

  • auto

• margin-top

  • auto

• margin

  • auto

• mask-clip

  • border
  • content
  • padding
  • text

• mask-image

  • multiple_mask_images
  • svg_masks

• mask-origin

  • fill-box
  • stroke-box
  • view-box
  • non_standard_values

• mask-type

  • applies_to_html

• mask

  • applies_to_html_elements
  • shorthand_for_mask_properties

• order

  • absolutely_positioned_flex_children

• position

  • fixed
  • sticky
  • position_relative_table_elements

• text-align

  • block_alignment_values
  • flow_relative_values_start_and_end
  • match-parent
  • justify-all

• text-combine-upright

  • digits

• text-decoration-line

  • blink

• text-decoration-style

  • wavy

• text-decoration

  • blink
  • shorthand

• text-emphasis-position

  • left_and_right

• text-indent

  • each-line
  • hanging

• text-orientation

  • sideways

• text-overflow

  • two_value_syntax
  • string
  • fade_value
  • fade_function

• touch-action

  • manipulation
  • double-tap-zoom
  • pinch-zoom
  • unidirectional-pan

• transform-origin

  • three_value_syntax
  • support_in_svg

• transform

  • 3d

• transition-property

  • IDENT_value

• transition

  • gradients

• z-index

  • negative_values

[foolip]

@Elchi3 pointed me to https://github.com/ddbeck/browser-compat-data/blob/master/css/properties/transform.json#L143 and I wonder how keywords like auto would be represented? matrix3d is a function so do those need to be moved to their own bucket to make room for plain keywords?

FWIW, a lot of this can probably be derived from https://github.com/tidoust/reffy-reports/tree/master/whatwg/css, which contains information scraped from all specs.

[ddbeck]

@foolip if it helps, I meant for the matching data to be as not-clever as I could manage. I intended for keywords to be a list of strings that correspond to the use of that feature, rather than keywords in the narrow sense of CSS (or any other specific compat area).

For the linked example, I intended for it to be understood as if a CSS declaration uses the transform property and its value contains one or more of the strings in the list of keywords then this feature matches. Some of that is inferred from its place in the hierarchy (css.properties.transform.3d.matches) — we could probably stand to have more explicit indications what a feature is (a property, a value, a function, an argument, etc.) but until then sometimes the semantics of matches will have to be informed by where we are in the hierarchy.

[foolip]

I see. Do you know who will be using this matching data? I'm curious to look at the concrete code using it, to see if it could be reused elsewhere. Understanding how the data is used also helps inform how to populate it.

[ddbeck]

Reading #3366 would probably be the best place to start. The matching data in the schema is brand new (merged a week ago), so we don't have examples of its use in the wild yet, but I expect webhint will start using it soon.

[connorshea]

Can you derive anything for this from regexes in TextMate language files? e.g. in VS Code or Atom?

[connorshea]

Also, can we add an attribute to the schema for "Regex explanation"?

Right now, these mean nothing to me:

^#[0-9a-fA-F]{4}(?:[0-9a-fA-F]{4})?$

^([\\d\\w%-]+|calc\\(.+\\))\\s+([\\d\\w%-]+|calc\\(.+\\))\\s+([\\d\\w-]+|calc\\(.+\\))$

For example, Wikidata properties have format as a regular expression, e.g. if you want to restrict the possible values for an ID in a given database to be only numbers, as well as syntax clarification, which is used to explain what the regex is supposed to do, since regex is generally not the most easy-to-read syntax.

[sideshowbarker]

Also, can we add an attribute to the schema for "Regex explanation"?

It seems like we should use the description field for that. In cases where the existing description field doesn’t very make clear what the regex is expressing, we could (should) update the description field to make it more clear.

Right now, these mean nothing to me:

^#[0-9a-fA-F]{4}(?:[0-9a-fA-F]{4})?$

For that one the current description field has this:

"description": "RGBA hexadecimal notation (<code>#RRGGBBAA</code>, <code>#RGBA</code>)"

That one at least seems sufficient to me — as far as also serving as an explanation of the regex. But if we wanted something more than that, the CSS spec has prose:

https://drafts.csswg.org/css-color/#typedef-hex-color

a hash character, "#", followed by some number of digits 0-9 or letters a-f… (3, 4, 6, or 8 hexadecimal digits)

^([\\d\\w%-]+|calc\\(.+\\))\\s+([\\d\\w%-]+|calc\\(.+\\))\\s+([\\d\\w-]+|calc\\(.+\\))$

So the description for that one is:

"description": "Three-value syntax"

…which means less to me than the regex does.

After looking at https://developer.mozilla.org/en-US/docs/Web/CSS/transform-origin#Syntax, it seems like a better description would be something like:

Three values separated by spaces: The first and second values may be a length, a percentage, or a keyword. The final value must be a length.

[ddbeck]

It seems to be there's a few points of confusion. People are having trouble understanding:

• how regexes are meant to be used (in general)
• what a given regex means
• what a given feature is for (i.e., what is the meaning of a name and a description)

I tried to capture the use of regexes a little bit in the schema doc. It would help me a lot to know how the docs aren't helping BCD contributors and consumers understand how to make the most of regexes.

Along similar lines, the meanings of individual regexes wasn't really considered something that BCD consumers would want to show to human readers, so I'm not really sure how a textual description of a regex would be useful to BCD consumers either. For authors of regexes, I kinda figured the regex test cases would serve as place to show how regexes hint at feature matches. But if those aren't helpful either, that would be good to know.

In the last case, yes, bad descriptions are bad. I'd welcome PRs that revise them to be helpfully concise instead of uselessly terse. 😄

[Elchi3]

This has never taken off. We're considering removal in #8945
Closing here, if you feel strongly about this let us let know in the removal issue.