Skip to content

Conversation

@tidoust
Copy link
Member

@tidoust tidoust commented Dec 16, 2025

This is meant to provide a simple patching mechanism for #1647 and #1737, based on a JSON-like structure, similar to the patching mechanism that we use for events (amend-event-data.js).

Patches get applied during curation after dropping duplicate definitions, and before the CSS extracts get consolidated.

The patching logic is initially restricted to adding syntaxes where they do not exist (no way to override an existing one for now) and to adding syntaxes to base definitions (no way to set the syntax of a newValues property).

The logic allows to say:

  1. Here is the syntax, period. That's the most direct way. But also the one that requires manual maintenance.
  2. Compute the syntax from the list of values, and optionally complete that list with this additional syntax. This allows to compute syntaxes such as <system-color> indirectly but still automatically from the spec.
  3. Use the syntax from that other construct (must be defined in the same spec). This allows to say that the syntax of -webkit-user-select is the same as that of user-select.

It will probably be useful to extend the patching logic slightly to allow overriding existing syntaxes over time. This would allow us to replace most patches in csspatches with a more convenient mechanism.

The initial list of patches is based on missing syntaxes identified in the mdn-webref analysis:
https://github.com/tidoust/mdn-webref/blob/main/report-syntax.md#syntax-mismatches-between-mdn-data-and-webref ... completed with some of the types highlighted in #1647.

At-rules and selectors are excluded for now. They can be patched too, just not done in that iteration. A few other ones are missing when it was not obvious to me that the syntax was correct, or when it seemed that the underlying spec could perhaps be updated.

In other words, the initial list of patches should be a good start but is not meant to be exhaustive.

This is meant to provide a simple patching mechanism for #1647 and #1737, based
on a JSON-like structure, similar to the patching mechanism that we use for
events (`amend-event-data.js`).

Patches get applied during curation after dropping duplicate definitions, and
before the CSS extracts get consolidated.

The patching logic is initially restricted to adding syntaxes where they do not
exist (no way to override an existing one for now) and to adding syntaxes to
base definitions (no way to set the syntax of a `newValues` property).

The logic allows to say:
1. Here is the syntax, period. That's the most direct way. But also the one
that requires manual maintenance.
2. Compute the syntax from the list of values, and optionally complete that
list with this additional syntax. This allows to compute syntaxes such as
`<system-color>` indirectly but still automatically from the spec.
3. Use the syntax from that other construct (must be defined in the same spec).
This allows to say that the syntax of `-webkit-user-select` is the same as that
of `user-select`.

It will probably be useful to extend the patching logic slightly to allow
overriding existing syntaxes over time. This would allow us to replace most
patches in `csspatches` with a more convenient mechanism.

The initial list of patches is based on missing syntaxes identified in the
mdn-webref analysis:
https://github.com/tidoust/mdn-webref/blob/main/report-syntax.md#syntax-mismatches-between-mdn-data-and-webref
... completed with some of the types highlighted in #1647.

At-rules and selectors are excluded for now. They can be patched too, just not
done in that iteration. A few other ones are missing when it was not obvious to
me that the syntax was correct, or when it seemed that the underlying spec could
perhaps be updated.

In other words, the initial list of patches should be a good start but is not
meant to be exhaustive.
Copy link
Member

@dontcallmedom dontcallmedom left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM; I think we probably ought to separate the patch data from the code (as I've thought for events patching for a while too), but that can be done separately.

I haven't verified the completeness/accuracy of the data - I'm assuming we can get that with your comparison tool.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants