@webref/css 5.4.4 → 6.0.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+This file documents breaking changes introduced in major releases of the
+`@webref/css` NPM package.
+
+Webref adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
+applied to data. A new major version is released whenever a breaking change is
+made to the data structure.
+
+
+## v6.0.0 - 2022-11-28
+
+Major re-write of CSS extracts listed in the package, following the release
+of [Reffy v11.0.0](https://github.com/w3c/reffy/blob/main/CHANGELOG.md#v1100---2022-11-28)
+
+### Breaking changes
+
+- Arrays are now used throughout instead of indexed objects.
+- Function names are no longer enclosed in `<` and `>` because they are not
+defined in specs with these characters (as opposed to types). Beware though,
+references to functions in value syntax do use enclosing `<` and `>` characters.
+- The property `valuespaces` at the root level is now named `values`. An array
+is used there as well. The `values` property lists both `function` and `type`
+definitions that are not namespaced to anything in particular (it used to also
+contain namespaced definitions).
+
+### Added
+
+- Selectors are now reported under a `selectors` property at the root level.
+- Possible values that some definition may take are now reported under a
+`values` property directly within the definition.
+- Functions and types that are namespaced to some other definition are included
+in the list of `values` of that definition.
+- Anomalies detected in the spec are now reported under a `warnings` property at
+the root of the extract. Four types of anomalies are reported:
+  1. **Missing definition**: when a production rule was found but when the spec
+  does not include a corresponding `<dfn>` (or when that `<dfn>` does not have a
+  `data-dfn-type` attribute that identifies a CSS construct)
+  2. **Duplicate definition**: when the spec defines the same term twice.
+  3. **Unmergeable definition**: when the spec defines the same property twice
+  and both definitions cannot be merged.
+  4. **Dangling value**: when the spec defines a CSS "value" definition
+  (`value`, `function` or `type`) for something and that something cannot be
+  found in the spec
+- To distinguish between `function`, `type` and `value` definitions listed in a
+`values` property, definitions that appear in a `values` property have a `type`
+property.
+
+### Additional notes
+
+- Only namespaced values associated with a definition are listed under its
+`values` property. Non-namespaced values are not. For instance, `<quote>` is not
+listed as a value of the `<content-list>` type, even though its value syntax
+references it. This is to avoid duplicating constructs in the extracts.
+- Values are only listed under the deepest definition to which they apply. For
+instance, `open-quote` is only listed as a value of `<quote>` but neither as a
+value of the `<content-list>` type that references `<quote>` nor as a value of
+the `content` property that references `<content-list>`. This is also to avoid
+duplicating constructs in the extracts.
+- Some of the extracts contain things that may look weird at first, but that is
+"by design". For instance, [CSS Will
+change](https://drafts.csswg.org/css-will-change-1/) defines a
+[`<custom-ident>`](https://drafts.csswg.org/css-will-change-1/#valdef-will-change-custom-ident)
+`value` construct whose actual value is the `<custom-ident>` `type` construct
+defined in CSS Values. Having both a namespaced `value` and a non-namespaced
+`<type>` is somewhat common in CSS specs.

package/CSS.json

@@ -3,8 +3,8 @@
     "title": "CSS 2",
     "url": "https://drafts.csswg.org/css2/"
   },
-  "properties": {
-    "z-index": {
+  "properties": [
+    {
       "name": "z-index",
       "value": "auto | <integer> | inherit",
       "initial": "auto",
@@ -14,12 +14,20 @@
       "computedValue": "as specified",
       "canonicalOrder": "per grammar",
       "media": "visual",
+      "values": [
+        {
+          "name": "auto",
+          "prose": "The stack level of the generated box in the current stacking context is 0. The box does not establish a new stacking context unless it is the root element.",
+          "type": "value",
+          "value": "auto"
+        }
+      ],
       "styleDeclaration": [
         "z-index",
         "zIndex"
       ]
     },
-    "page-break-before": {
+    {
       "name": "page-break-before",
       "value": "auto | always | avoid | left | right | inherit",
       "initial": "auto",
@@ -29,12 +37,44 @@
       "computedValue": "as specified",
       "canonicalOrder": "per grammar",
       "media": "visual, paged",
+      "values": [
+        {
+          "name": "auto",
+          "prose": "Neither force nor forbid a page break before (after, inside) the generated box.",
+          "type": "value",
+          "value": "auto"
+        },
+        {
+          "name": "always",
+          "prose": "Always force a page break before (after) the generated box.",
+          "type": "value",
+          "value": "always"
+        },
+        {
+          "name": "avoid",
+          "prose": "Avoid a page break before (after, inside) the generated box.",
+          "type": "value",
+          "value": "avoid"
+        },
+        {
+          "name": "left",
+          "prose": "Force one or two page breaks before (after) the generated box so that the next page is formatted as a left page.",
+          "type": "value",
+          "value": "left"
+        },
+        {
+          "name": "right",
+          "prose": "Force one or two page breaks before (after) the generated box so that the next page is formatted as a right page.",
+          "type": "value",
+          "value": "right"
+        }
+      ],
       "styleDeclaration": [
         "page-break-before",
         "pageBreakBefore"
       ]
     },
-    "page-break-after": {
+    {
       "name": "page-break-after",
       "value": "auto | always | avoid | left | right | inherit",
       "initial": "auto",
@@ -44,12 +84,44 @@
       "computedValue": "as specified",
       "canonicalOrder": "per grammar",
       "media": "visual, paged",
+      "values": [
+        {
+          "name": "auto",
+          "prose": "Neither force nor forbid a page break before (after, inside) the generated box.",
+          "type": "value",
+          "value": "auto"
+        },
+        {
+          "name": "always",
+          "prose": "Always force a page break before (after) the generated box.",
+          "type": "value",
+          "value": "always"
+        },
+        {
+          "name": "avoid",
+          "prose": "Avoid a page break before (after, inside) the generated box.",
+          "type": "value",
+          "value": "avoid"
+        },
+        {
+          "name": "left",
+          "prose": "Force one or two page breaks before (after) the generated box so that the next page is formatted as a left page.",
+          "type": "value",
+          "value": "left"
+        },
+        {
+          "name": "right",
+          "prose": "Force one or two page breaks before (after) the generated box so that the next page is formatted as a right page.",
+          "type": "value",
+          "value": "right"
+        }
+      ],
       "styleDeclaration": [
         "page-break-after",
         "pageBreakAfter"
       ]
     },
-    "page-break-inside": {
+    {
       "name": "page-break-inside",
       "value": "avoid | auto | inherit",
       "initial": "auto",
@@ -59,31 +131,354 @@
       "computedValue": "as specified",
       "canonicalOrder": "per grammar",
       "media": "visual, paged",
+      "values": [
+        {
+          "name": "auto",
+          "prose": "Neither force nor forbid a page break before (after, inside) the generated box.",
+          "type": "value",
+          "value": "auto"
+        },
+        {
+          "name": "always",
+          "prose": "Always force a page break before (after) the generated box.",
+          "type": "value",
+          "value": "always"
+        },
+        {
+          "name": "avoid",
+          "prose": "Avoid a page break before (after, inside) the generated box.",
+          "type": "value",
+          "value": "avoid"
+        },
+        {
+          "name": "left",
+          "prose": "Force one or two page breaks before (after) the generated box so that the next page is formatted as a left page.",
+          "type": "value",
+          "value": "left"
+        },
+        {
+          "name": "right",
+          "prose": "Force one or two page breaks before (after) the generated box so that the next page is formatted as a right page.",
+          "type": "value",
+          "value": "right"
+        }
+      ],
       "styleDeclaration": [
         "page-break-inside",
         "pageBreakInside"
       ]
     }
-  },
-  "atrules": {},
-  "valuespaces": {
-    "<uri>": {
-      "prose": "URI values (Uniform Resource Identifiers, see [RFC3986], which includes URLs, URNs, etc) in this specification are denoted by <uri>. The functional notation used to designate URIs in property values is \"url()\", as in:"
+  ],
+  "atrules": [
+    {
+      "name": "@import",
+      "prose": "The @import rule allows users to import style rules from other style sheets. In CSS 2, any @import rules must precede all other rules (except the @charset rule, if present). See the section on parsing for when user agents must ignore @import rules. The @import keyword must be followed by the URI of the style sheet to include. A string is also allowed; it will be interpreted as if it had url(...) around it.",
+      "descriptors": []
+    },
+    {
+      "name": "@media",
+      "descriptors": [],
+      "values": [
+        {
+          "name": "all",
+          "prose": "Suitable for all devices.",
+          "type": "value",
+          "value": "all",
+          "values": [
+            {
+              "name": "inherit",
+              "type": "value",
+              "value": "inherit"
+            }
+          ]
+        },
+        {
+          "name": "braille",
+          "prose": "Intended for braille tactile feedback devices.",
+          "type": "value",
+          "value": "braille"
+        },
+        {
+          "name": "embossed",
+          "prose": "Intended for paged braille printers.",
+          "type": "value",
+          "value": "embossed"
+        },
+        {
+          "name": "handheld",
+          "prose": "Intended for handheld devices (typically small screen, limited bandwidth).",
+          "type": "value",
+          "value": "handheld"
+        },
+        {
+          "name": "print",
+          "prose": "Intended for paged material and for documents viewed on screen in print preview mode. Please consult the section on paged media for information about formatting issues that are specific to paged media.",
+          "type": "value",
+          "value": "print"
+        },
+        {
+          "name": "projection",
+          "prose": "Intended for projected presentations, for example projectors. Please consult the section on paged media for information about formatting issues that are specific to paged media.",
+          "type": "value",
+          "value": "projection"
+        },
+        {
+          "name": "screen",
+          "prose": "Intended primarily for color computer screens.",
+          "type": "value",
+          "value": "screen"
+        },
+        {
+          "name": "speech",
+          "prose": "Intended for speech synthesizers. Note: CSS2 (1998) had a similar media type called aural for this purpose.",
+          "type": "value",
+          "value": "speech"
+        },
+        {
+          "name": "tty",
+          "prose": "Intended for media using a fixed-pitch character grid (such as teletypes, terminals, or portable devices with limited display capabilities). Authors should not use pixel units with the \"tty\" media type.",
+          "type": "value",
+          "value": "tty"
+        },
+        {
+          "name": "tv",
+          "prose": "Intended for television-type devices (low resolution, color, limited-scrollability screens, sound available).",
+          "type": "value",
+          "value": "tv"
+        }
+      ]
+    },
+    {
+      "name": "@page",
+      "prose": "Authors can specify the margins of a page box inside an @page rule. An @page rule consists of the keyword \"@page\", followed by an optional page selector, followed by a block containing declarations and at-rules. Comments and white space are allowed, but optional, between the @page token and the page selector and between the page selector and the block. The declarations in an @page rule are said to be in the page context.",
+      "descriptors": []
+    }
+  ],
+  "selectors": [
+    {
+      "name": ":lang"
+    },
+    {
+      "name": ":first-line"
+    },
+    {
+      "name": ":first-letter"
     },
-    "<margin-width>": {
-      "prose": "The properties defined in this section refer to the <margin-width> value type, which may take one of the following values:"
+    {
+      "name": ":before"
     },
-    "<padding-width>": {
-      "prose": "The properties defined in this section refer to the <padding-width> value type, which may take one of the following values:"
+    {
+      "name": ":after"
     },
-    "<border-width>": {
-      "prose": "The border width properties specify the width of the border area. The properties defined in this section refer to the <border-width> value type, which may take one of the following values:"
+    {
+      "name": ":left",
+      "prose": "All pages are automatically classified by user agents into either the :left or :right pseudo-class. Whether the first page of a document is :left or :right depends on the major writing direction of the root element. For example, the first page of a document with a left-to-right major writing direction would be a :right page, and the first page of a document with a right-to-left major writing direction would be a :left page. To explicitly force a document to begin printing on a left or right page, authors can insert a page break before the first generated box."
+    },
+    {
+      "name": ":right",
+      "prose": "All pages are automatically classified by user agents into either the :left or :right pseudo-class. Whether the first page of a document is :left or :right depends on the major writing direction of the root element. For example, the first page of a document with a left-to-right major writing direction would be a :right page, and the first page of a document with a right-to-left major writing direction would be a :left page. To explicitly force a document to begin printing on a left or right page, authors can insert a page break before the first generated box."
+    },
+    {
+      "name": ":first",
+      "prose": "Authors may also specify style for the first page of a document with the :first pseudo-class:"
+    }
+  ],
+  "values": [
+    {
+      "name": "<identifier>",
+      "type": "type"
+    },
+    {
+      "name": "<uri>",
+      "prose": "URI values (Uniform Resource Identifiers, see [RFC3986], which includes URLs, URNs, etc) in this specification are denoted by <uri>. The functional notation used to designate URIs in property values is \"url()\", as in:",
+      "type": "type"
+    },
+    {
+      "name": "<margin-width>",
+      "prose": "The properties defined in this section refer to the <margin-width> value type, which may take one of the following values:",
+      "type": "type"
+    },
+    {
+      "name": "<padding-width>",
+      "prose": "The properties defined in this section refer to the <padding-width> value type, which may take one of the following values:",
+      "type": "type",
+      "values": [
+        {
+          "name": "<length>",
+          "prose": "Specifies a fixed width.",
+          "type": "value",
+          "value": "<length>"
+        },
+        {
+          "name": "<percentage>",
+          "prose": "The percentage is calculated with respect to the width of the generated box’s containing block, even for padding-top and padding-bottom. If the containing block’s width depends on this element, then the resulting layout is undefined in CSS 2.",
+          "type": "value",
+          "value": "<percentage>"
+        }
+      ]
+    },
+    {
+      "name": "<border-width>",
+      "prose": "The border width properties specify the width of the border area. The properties defined in this section refer to the <border-width> value type, which may take one of the following values:",
+      "type": "type",
+      "values": [
+        {
+          "name": "thin",
+          "prose": "A thin border.",
+          "type": "value",
+          "value": "thin"
+        },
+        {
+          "name": "medium",
+          "prose": "A medium border.",
+          "type": "value",
+          "value": "medium"
+        },
+        {
+          "name": "thick",
+          "prose": "A thick border.",
+          "type": "value",
+          "value": "thick"
+        },
+        {
+          "name": "<length>",
+          "prose": "The border’s thickness has an explicit value. Explicit border widths cannot be negative.",
+          "type": "value",
+          "value": "<length>"
+        }
+      ]
+    },
+    {
+      "name": "<border-style>",
+      "prose": "The border style properties specify the line style of a box’s border (solid, double, dashed, etc.). The properties defined in this section refer to the <border-style> value type, which may take one of the following values:",
+      "type": "type",
+      "values": [
+        {
+          "name": "none",
+          "prose": "No border; the computed border width is zero.",
+          "type": "value",
+          "value": "none"
+        },
+        {
+          "name": "hidden",
+          "prose": "Same as none, except in terms of border conflict resolution for table elements.",
+          "type": "value",
+          "value": "hidden"
+        },
+        {
+          "name": "dotted",
+          "prose": "The border is a series of dots.",
+          "type": "value",
+          "value": "dotted"
+        },
+        {
+          "name": "dashed",
+          "prose": "The border is a series of short line segments.",
+          "type": "value",
+          "value": "dashed"
+        },
+        {
+          "name": "solid",
+          "prose": "The border is a single line segment.",
+          "type": "value",
+          "value": "solid"
+        },
+        {
+          "name": "double",
+          "prose": "The border is two solid lines. The sum of the two lines and the space between them equals the value of border-width.",
+          "type": "value",
+          "value": "double"
+        },
+        {
+          "name": "groove",
+          "prose": "The border looks as though it were carved into the canvas.",
+          "type": "value",
+          "value": "groove"
+        },
+        {
+          "name": "ridge",
+          "prose": "The opposite of groove: the border looks as though it were coming out of the canvas.",
+          "type": "value",
+          "value": "ridge"
+        },
+        {
+          "name": "inset",
+          "prose": "The border makes the box look as though it were embedded in the canvas.",
+          "type": "value",
+          "value": "inset"
+        },
+        {
+          "name": "outset",
+          "prose": "The opposite of inset: the border makes the box look as though it were coming out of the canvas.",
+          "type": "value",
+          "value": "outset"
+        }
+      ]
+    },
+    {
+      "name": "<shape>",
+      "prose": "In CSS 2, the only valid <shape> value is: rect(<top>, <right>, <bottom>, <left>) where <top> and <bottom> specify offsets from the top border edge of the box, and <right>, and <left> specify offsets from the left border edge of the box. Authors should separate offset values with commas. User agents must support separation with commas, but may also support separation without commas (but not a combination), because a previous revision of this specification was ambiguous in this respect. <top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box). When coordinates are rounded to pixel coordinates, care should be taken that no pixels remain visible when <left> and <right> have the same value (or <top> and <bottom> have the same value), and conversely that no pixels within the element’s border box remain hidden when these values are auto.",
+      "type": "type"
+    },
+    {
+      "name": "<top>",
+      "prose": "<top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box).",
+      "type": "type",
+      "values": [
+        {
+          "name": "auto",
+          "prose": "<top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box).",
+          "type": "value",
+          "value": "auto"
+        }
+      ]
+    },
+    {
+      "name": "<right>",
+      "prose": "<top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box).",
+      "type": "type",
+      "values": [
+        {
+          "name": "auto",
+          "prose": "<top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box).",
+          "type": "value",
+          "value": "auto"
+        }
+      ]
+    },
+    {
+      "name": "<bottom>",
+      "prose": "<top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box).",
+      "type": "type",
+      "values": [
+        {
+          "name": "auto",
+          "prose": "<top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box).",
+          "type": "value",
+          "value": "auto"
+        }
+      ]
+    },
+    {
+      "name": "<left>",
+      "prose": "<top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box).",
+      "type": "type",
+      "values": [
+        {
+          "name": "auto",
+          "prose": "<top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box).",
+          "type": "value",
+          "value": "auto"
+        }
+      ]
     },
-    "<border-style>": {
-      "prose": "The border style properties specify the line style of a box’s border (solid, double, dashed, etc.). The properties defined in this section refer to the <border-style> value type, which may take one of the following values:"
+    {
+      "name": "<absolute-size>",
+      "type": "type"
     },
-    "<shape>": {
-      "prose": "In CSS 2, the only valid <shape> value is: rect(<top>, <right>, <bottom>, <left>) where <top> and <bottom> specify offsets from the top border edge of the box, and <right>, and <left> specify offsets from the left border edge of the box. Authors should separate offset values with commas. User agents must support separation with commas, but may also support separation without commas (but not a combination), because a previous revision of this specification was ambiguous in this respect. <top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box). When coordinates are rounded to pixel coordinates, care should be taken that no pixels remain visible when <left> and <right> have the same value (or <top> and <bottom> have the same value), and conversely that no pixels within the element’s border box remain hidden when these values are auto."
+    {
+      "name": "<relative-size>",
+      "type": "type"
     }
-  }
+  ]
 }

package/README.md

@@ -15,7 +15,7 @@ for (const [shortname, data] of Object.entries(parsedFiles)) {
 }
 ```
 
-CSS fragments that appear in the objects, in other words the contents of the `properties[].value`, `properties[].newValues`, `atrules[].value`, `atrules[].descriptors[].value` and `valuespaces[].value` properties can be parsed with the [CSSTree Value Definition Syntax parser](https://github.com/csstree/csstree/blob/master/docs/definition-syntax.md#value-definition-syntax). Example:
+CSS fragments that appear in the objects, in other words the contents of the `properties[].value`, `properties[].newValues`, `atrules[].value`, `atrules[].descriptors[].value`, `selectors[].value` and `values[].value` properties can be parsed with the [CSSTree Value Definition Syntax parser](https://github.com/csstree/csstree/blob/master/docs/definition-syntax.md#value-definition-syntax). Example:
 
 ```js
 const css = require('@webref/css');
@@ -23,10 +23,10 @@ const { definitionSyntax } = require('css-tree');
 
 const parsedFiles = await css.listAll();
 for (const [shortname, data] of Object.entries(parsedFiles)) {
-  for (const [name, desc] of Object.entries(data.properties)) {
-    if (desc.value) {
+  for (const property of data.properties) {
+    if (property.value) {
       try {
-        const ast = definitionSyntax.parse(desc.value);
+        const ast = definitionSyntax.parse(property.value);
         // do something with the ast
       }
       catch {