Skip to content

Commit b2dea8a

Browse files
tidousttidoust
committed
Move patches to a separate file in csspatches folder
Also moved closer to pure JSON where possible.
1 parent 41375e7 commit b2dea8a

File tree

3 files changed

+190
-182
lines changed

3 files changed

+190
-182
lines changed

‎ed/csspatches/README.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
# CSS patches
22

3-
These are patches applied to the CSS extracts scraped from specs to produce the `@webref/css` package. These patches can break as specs are updated and thus need ongoing maintenance.
3+
The folder contains two types of patches applied to the CSS extracts scraped from specs during curation to produce the `@webref/css` package:
44

5-
For details on how to create and update patches, please see the [Web IDL patches documentation](../idlpatches/README.md).
5+
- The [`syntax-patches.js`](./syntax-patches.js) file contains a list of syntaxes for situations where that syntax cannot be automatically extracted from the underlying spec because it is defined in non-machine-readable prose. These patches are usually permanent in that they cover situations where it is unlikely that the underlying spec will be updated to make the syntax more explicit.
6+
- The `*.json.patch` files contains extract file patches applied to CSS extracts. These patches are intended to be temporary while the spec gets fixed, and are typically associated with an issue or pull request raised against the underlying spec. These patches typically break as specs get updated. For details on how to create and update file patches, please see the [Web IDL patches documentation](../idlpatches/README.md).
67

7-
Note that Webref has two additional mechanisms to patch CSS data:
8-
- The [`tools/drop-css-property-duplicates.js`](../../tools/drop-css-property-duplicates.js) script drops duplicates for situations where definition in one spec is known to override the same definition in another spec.
9-
- The [`tools/amend-css-syntaxes.js`](../../tools/amend-css-syntaxes.js) script adds syntaxes of CSS constructs in situations where the spec details a syntax in non-machine-readable prose, e.g., because the syntax needs to be derived from a list of values.
8+
On top of these patches, note that curation also drops duplicate definitions through the [`tools/drop-css-property-duplicates.js`](../../tools/drop-css-property-duplicates.js) script which handles situations where definitions in one spec override definitions in another spec (for example, definitions in CSS modules overrride definitions in CSS 2).

‎ed/csspatches/syntax-patches.js‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
/******************************************************************************
2+
* List of CSS syntax patches
3+
*
4+
* The list follows a JSON-like structure, represented as a JS object so that
5+
* comments can be added and so that backticks may be used to split long
6+
* syntaxes over multiple lines to ease readability.
7+
*
8+
* Syntax patches are currently restricted to adding a syntax to CSS constructs
9+
* for which no syntax could be extracted from the underlying spec. They cannot
10+
* be used to override the syntax of a CSS construct (a full patch file is
11+
* needed for that, check the instructions in the README).
12+
*
13+
* Also, patches should only be used for situations where the spec cannot
14+
* easily be updated to make the syntax more explicit, e.g., because defining
15+
* the syntax in prose is seen as more convenient.
16+
*
17+
* The list is an indexed object where keys are the shortnames of the
18+
* specifications to patch and where values are themselves an indexed object
19+
* where:
20+
* - keys are the name of the CSS constructs to patch, for example:
21+
* `<system-color>`
22+
* - values define the patch to apply
23+
*
24+
* If the CSS construct to target is nested (for example, the descriptor of an
25+
* at-rule), start with the name of the root constructor, add a `/`, and then
26+
* the name of the actual construct. For example: `@page/page/<page-size>` to
27+
* target the `<page-size>` type of the `page` descriptor of the `@page`
28+
* at-rule.
29+
*
30+
* The patch value can either be:
31+
* - A string, which gets interpreted as the CSS syntax to set. For example:
32+
* '<custom-ident>'
33+
* - An object with one or more of the following keys:
34+
* - `useValues`: a boolean flag. When set, the code builds the syntax of the
35+
* CSS construct from the list of CSS values that are defined for it in the
36+
* spec (and that could be extracted).
37+
* - `newValues`: a string that contains some additional syntax to add on top
38+
* of existing values. The `useValues` flag must also be set (there is no
39+
* way to set the syntax of an extended definition for now)
40+
* - `sameAs`: a reference to another CSS construct in the same spec that
41+
* provides the syntax to use. Cannot be used with any of the other keys.
42+
*
43+
* Trailing spaces in syntaxes will be trimmed, and so will extra spaces.
44+
* That's to ease patch readability. For example: `
45+
* <basic-shape-rect> |
46+
* <circle()> | <ellipse()>
47+
* `
48+
* ... becomes `<basic-shape-rect> | <circle()> | <ellipse()>` once the patch
49+
* is applied.
50+
*
51+
* It is good practice to start a patch with a comment that links to the
52+
* the construct definition in the spec.
53+
*
54+
* The underlying patching logic is in tools/amend-css-syntaxes.js.
55+
*
56+
* Note: the logic could be extended over time as needed to:
57+
* - Allow overriding an existing syntax. That would allow replacing most
58+
* patch files in this folder. The underlying PR should be reported in a
59+
* `pending` key and/or the incorrect syntax should be recorded to make
60+
* sure we do not miss updates.
61+
* - Allow dropping an existing syntax. That has never been needed until now.
62+
* - Allow adding/overriding new values of an extended definition. That could
63+
* also prove useful.
64+
*****************************************************************************/
65+
export default {
66+
// https://drafts.csswg.org/css-cascade-6/#scope-syntax
67+
"css-cascade-6": {
68+
"<scope-start>": "<selector-list>",
69+
"<scope-end>": "<selector-list>"
70+
},
71+
72+
// https://drafts.csswg.org/css-color-4/#typedef-system-color
73+
// https://drafts.csswg.org/css-color-4/#typedef-deprecated-color
74+
// https://drafts.csswg.org/css-color-4/#typedef-named-color
75+
"css-color-4": {
76+
"<system-color>": {
77+
"useValues": true,
78+
"newValues": "<deprecated-color>"
79+
},
80+
"<deprecated-color>": {
81+
"useValues": true
82+
},
83+
"<named-color>": {
84+
"useValues": true,
85+
"newValues": "transparent"
86+
}
87+
},
88+
89+
// https://drafts.csswg.org/css-counter-styles-3/#typedef-counter-style-name
90+
"css-counter-styles-3": {
91+
"<counter-style-name>": "<custom-ident>"
92+
},
93+
94+
// https://drafts.csswg.org/css-fonts-4/#typedef-font-palette-palette-identifier
95+
"css-fonts-4": {
96+
"font-palette/<palette-identifier>": "<dashed-ident>"
97+
},
98+
99+
// https://drafts.csswg.org/css-lists-3/#typedef-counter-name
100+
"css-lists-3": {
101+
"<counter-name>": "<custom-ident>"
102+
},
103+
104+
// https://drafts.csswg.org/css-overflow-5/#typedef-scroll-button-direction
105+
"css-overflow-5": {
106+
"<scroll-button-direction>": {
107+
"useValues": true
108+
}
109+
},
110+
111+
// https://drafts.csswg.org/css-page-3/#typedef-page-size-page-size
112+
"css-page-3": {
113+
"@page/size/<page-size>": {
114+
"useValues": true
115+
}
116+
},
117+
118+
// https://drafts.csswg.org/css-shapes-1/#supported-basic-shapes
119+
"css-shapes-1": {
120+
"<basic-shape>": `
121+
<basic-shape-rect> |
122+
<circle()> | <ellipse()> | <polygon()> |
123+
<path()> | <shape()>
124+
`
125+
},
126+
127+
// https://drafts.csswg.org/css-syntax-3/#the-anb-type
128+
"css-syntax-3": {
129+
"<n-dimension>": "<dimension-token>",
130+
"<ndash-dimension>": "<dimension-token>",
131+
"<ndashdigit-dimension>": "<dimension-token>",
132+
"<ndashdigit-ident>": "<ident-token>",
133+
"<dashndashdigit-ident>": "<ident-token>",
134+
"<signed-integer>": "<number-token>",
135+
"<signless-integer>": "<number-token>"
136+
},
137+
138+
// https://drafts.csswg.org/css-transforms-2/#transform-functions
139+
"css-transforms-2": {
140+
"<transform-function>": `
141+
<scale()> | <scaleX()> | <scaleY()> | <scaleZ()> |
142+
<translate3d()> | <translate()> | <translateX()> | <translateY()> | <translateZ()> |
143+
<rotate3d()> <rotate()> | <rotateX()> | <rotateY()> | <rotateZ()> |
144+
<skew()> | <skewX()> | <skewY()> |
145+
<matrix3d()> | <matrix()> | <perspective()>
146+
`,
147+
},
148+
149+
// https://drafts.csswg.org/css-ui-4/#propdef--webkit-user-select
150+
// https://drafts.csswg.org/css-ui-4/#typedef-outline-line-style
151+
"css-ui-4": {
152+
"-webkit-user-select": {
153+
"sameAs": "user-select"
154+
},
155+
// Same as <line-style> but "auto" replaces "hidden"
156+
"<outline-line-style>": `
157+
none | auto | dotted | dashed | solid | double |
158+
groove | ridge | inset | outset
159+
`
160+
},
161+
162+
// https://drafts.csswg.org/css-values-4/#integers
163+
"css-values-4": {
164+
"<integer>": "<number-token>"
165+
},
166+
167+
// https://drafts.csswg.org/css2/#value-def-absolute-size
168+
// https://drafts.csswg.org/css2/#value-def-relative-size
169+
// https://drafts.csswg.org/css2/#value-def-shape
170+
"CSS2": {
171+
"<absolute-size>": `
172+
xx-small | x-small | small | medium |
173+
large | x-large | xx-large
174+
`,
175+
"<relative-size>": "larger | smaller",
176+
"<shape>": "rect(<top>, <right>, <bottom>, <left>)"
177+
},
178+
179+
// https://svgwg.org/svg2-draft/pservers.html#StopColorProperty
180+
// https://svgwg.org/svg2-draft/pservers.html#StopOpacityProperty
181+
"SVG2": {
182+
"stop-color": `<'color'>`,
183+
"stop-opacity": `<'opacity'>`
184+
}
185+
};

‎tools/amend-css-syntaxes.js‎

Lines changed: 1 addition & 177 deletions
Original file line numberDiff line numberDiff line change
@@ -10,188 +10,12 @@
1010
* update (default is "curated")
1111
*/
1212

13-
/******************************************************************************
14-
* List of CSS syntax patches to apply.
15-
*
16-
* The list is an indexed object where keys are the shortnames of the
17-
* specifications to patch and where values are themselves an indexed object
18-
* where:
19-
* - keys are the name of the CSS constructs to patch, for example:
20-
* `<system-color>`
21-
* - values define the patch to apply
22-
*
23-
* If the CSS construct to target is nested (for example, the descriptor of an
24-
* at-rule), start with the name of the root constructor, add a `/`, and then
25-
* the name of the actual construct. For example: `@page/page/<page-size>` to
26-
* target the `<page-size>` type of the `page` descriptor of the `@page`
27-
* at-rule.
28-
*
29-
* The patch value can either be:
30-
* - A string, which gets interpreted as the CSS syntax to set. For example:
31-
* '<custom-ident>'
32-
* - An object with one or more of the following keys:
33-
* - `useValues`: a boolean flag. When set, the code builds the syntax of the
34-
* CSS construct from the list of CSS values that are defined for it in the
35-
* spec (and that could be extracted).
36-
* - `newValues`: a string that contains some additional syntax to add on top
37-
* of existing values. The `useValues` flag must also be set (there is no
38-
* way to set the syntax of an extended definition for now)
39-
* - `sameAs`: a reference to another CSS construct in the same spec that
40-
* provides the syntax to use. Cannot be used with any of the other keys.
41-
*
42-
* Trailing spaces in syntaxes are trimmed, and so are extra spaces. That's
43-
* to ease patch readability. For example: `
44-
* <basic-shape-rect> |
45-
* <circle()> | <ellipse()>
46-
* `
47-
* ... becomes '<basic-shape-rect> | <circle()> | <ellipse()>'
48-
*
49-
* It is good practice to start a patch with a comment that links to the
50-
* the construct definition in the spec.
51-
*
52-
* Patches should only be used for syntaxes that cannot be correctly extracted
53-
* from specs.
54-
*
55-
* Note: the logic could be extended over time as needed to:
56-
* - Allow overriding an existing syntax. That would allow replacing most
57-
* patches in "csspatches". The underlying PR should be reported in a
58-
* `pending` key and/or the incorrect syntax should be recorded to make
59-
* sure we do not miss updates.
60-
* - Allow dropping an existing syntax. That has never been needed until now.
61-
* - Allow adding/overriding new values of an extended definition. That could
62-
* also prove useful.
63-
*****************************************************************************/
64-
const patches = {
65-
// https://drafts.csswg.org/css-cascade-6/#scope-syntax
66-
'css-cascade-6': {
67-
'<scope-start>': '<selector-list>',
68-
'<scope-end>': '<selector-list>'
69-
},
70-
71-
// https://drafts.csswg.org/css-color-4/#typedef-system-color
72-
// https://drafts.csswg.org/css-color-4/#typedef-deprecated-color
73-
// https://drafts.csswg.org/css-color-4/#typedef-named-color
74-
'css-color-4': {
75-
'<system-color>': {
76-
useValues: true,
77-
newValues: '<deprecated-color>'
78-
},
79-
'<deprecated-color>': {
80-
useValues: true
81-
},
82-
'<named-color>': {
83-
useValues: true,
84-
newValues: 'transparent'
85-
}
86-
},
87-
88-
// https://drafts.csswg.org/css-counter-styles-3/#typedef-counter-style-name
89-
'css-counter-styles-3': {
90-
'<counter-style-name>': '<custom-ident>'
91-
},
92-
93-
// https://drafts.csswg.org/css-fonts-4/#typedef-font-palette-palette-identifier
94-
'css-fonts-4': {
95-
'font-palette/<palette-identifier>': '<dashed-ident>'
96-
},
97-
98-
// https://drafts.csswg.org/css-lists-3/#typedef-counter-name
99-
'css-lists-3': {
100-
'<counter-name>': '<custom-ident>'
101-
},
102-
103-
// https://drafts.csswg.org/css-overflow-5/#typedef-scroll-button-direction
104-
'css-overflow-5': {
105-
'<scroll-button-direction>': {
106-
useValues: true
107-
}
108-
},
109-
110-
// https://drafts.csswg.org/css-page-3/#typedef-page-size-page-size
111-
'css-page-3': {
112-
'@page/size/<page-size>': {
113-
useValues: true
114-
}
115-
},
116-
117-
// https://drafts.csswg.org/css-shapes-1/#supported-basic-shapes
118-
'css-shapes-1': {
119-
'<basic-shape>': `
120-
<basic-shape-rect> |
121-
<circle()> | <ellipse()> | <polygon()> |
122-
<path()> | <shape()>
123-
`
124-
},
125-
126-
// https://drafts.csswg.org/css-syntax-3/#the-anb-type
127-
'css-syntax-3': {
128-
'<n-dimension>': '<dimension-token>',
129-
'<ndash-dimension>': '<dimension-token>',
130-
'<ndashdigit-dimension>': '<dimension-token>',
131-
'<ndashdigit-ident>': '<ident-token>',
132-
'<dashndashdigit-ident>': '<ident-token>',
133-
'<signed-integer>': '<number-token>',
134-
'<signless-integer>': '<number-token>'
135-
},
136-
137-
// https://drafts.csswg.org/css-transforms-2/#transform-functions
138-
'css-transforms-2': {
139-
'<transform-function>': `
140-
<scale()> | <scaleX()> | <scaleY()> | <scaleZ()> |
141-
<translate3d()> | <translate()> | <translateX()> | <translateY()> | <translateZ()> |
142-
<rotate3d()> <rotate()> | <rotateX()> | <rotateY()> | <rotateZ()> |
143-
<skew()> | <skewX()> | <skewY()> |
144-
<matrix3d()> | <matrix()> | <perspective()>
145-
`,
146-
},
147-
148-
// https://drafts.csswg.org/css-ui-4/#propdef--webkit-user-select
149-
// https://drafts.csswg.org/css-ui-4/#typedef-outline-line-style
150-
'css-ui-4': {
151-
'-webkit-user-select': {
152-
sameAs: 'user-select'
153-
},
154-
// Same as <line-style> but 'auto' replaces 'hidden'
155-
'<outline-line-style>': `
156-
none | auto | dotted | dashed | solid | double |
157-
groove | ridge | inset | outset
158-
`
159-
},
160-
161-
// https://drafts.csswg.org/css-values-4/#integers
162-
'css-values-4': {
163-
'<integer>': '<number-token>'
164-
},
165-
166-
// https://drafts.csswg.org/css2/#value-def-absolute-size
167-
// https://drafts.csswg.org/css2/#value-def-relative-size
168-
// https://drafts.csswg.org/css2/#value-def-shape
169-
'CSS2': {
170-
'<absolute-size>': `
171-
xx-small | x-small | small | medium |
172-
large | x-large | xx-large
173-
`,
174-
'<relative-size>': 'larger | smaller',
175-
'<shape>': 'rect(<top>, <right>, <bottom>, <left>)'
176-
},
177-
178-
// https://svgwg.org/svg2-draft/pservers.html#StopColorProperty
179-
// https://svgwg.org/svg2-draft/pservers.html#StopOpacityProperty
180-
'SVG2': {
181-
'stop-color': `<'color'>`,
182-
'stop-opacity': `<'opacity'>`
183-
}
184-
};
185-
186-
187-
/******************************************************************************
188-
* Patching logic
189-
*****************************************************************************/
19013
import fs from 'node:fs/promises';
19114
import path from 'node:path';
19215
import { fileURLToPath } from 'node:url';
19316
import { loadJSON } from './utils.js';
19417
import { expandCrawlResult, isLatestLevelThatPasses } from 'reffy';
18+
import patches from '../ed/csspatches/syntax-patches.js';
19519

19620
/**
19721
* Trim a patch syntax

0 commit comments

Comments
 (0)