From df11dae1a6d003cc2eb15e56bd6db20541cbd31b Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Mon, 4 Dec 2023 20:29:35 -0800 Subject: [PATCH 01/43] New page: CSS syntax error handling --- .../css/css_syntax/error_handling/index.md | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 files/en-us/web/css/css_syntax/error_handling/index.md diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md new file mode 100644 index 000000000000000..d2c7a2cb0df6dd1 --- /dev/null +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -0,0 +1,90 @@ +--- +title: CSS syntax error handling +slug: Web/CSS/CSS_syntax/error_handling +page-type: guide +--- + +{{CSSRef}} + +When an error is made in CSS, instead of [throwing an error](/en-US/docs/Web/JavaScript/Reference/Errors) like in JavaScript, the browser will gracefully recover, skipping over the invalid content. While the user agent won't alert you to CSS errors, the user agent won't fail either. This is a feature of CSS, not a bug. + +In CSS, when an error is made, the user-agent parser ignores the lines containting the errors, discarding the minimum amount of content before returning to parsing as normal. This error-recovery is done because, as new features are added to CSS, a browser may not recognize new features and will simply discard the line with the content with what it may currently view as error. This enables adding new features to CSS without worrying that anything, other than the new feature, is broken in older browsers. It also enables including both old and new syntax, in that order, so the old syntax is rendered until the new syntax becomes parsed as valid. + +The type of content that gets ignored, depends on the type of error. For example, + +- For errors in at-rules, whether a single line or the entire at-rule fails depends on the at-rule and the type of error. +- If the error is an invalid selector, the entire declaration block is ignored. +- If a semi-colon is omitted between property declarations, the missing semi-colon causes an invalid value, so the declaration is ignored. +- If the error is a property name or value, such as an unrecognized property name or invalid data type, the declaration is ignored. +- If the error is a missing end-bracket, what gets ignored depends on whether the user-agent can parse the error as nested CSS. + +After each declaration, style rule, at-rule, etc. is parsed, the user agent checks the parsed content against its expected grammar for that construct. If it does not match the expected grammar for that construct, it is invalid, and is ignored. + +## CSS parser errors + +### At-rule errors + +The `@`, known in the CSS specifications as an ``, indicates the beginning of an at-rule. CSS includes single line at-rules, such as such as {{cssxref("@import")}} or {{cssxref("@layer")}} that contain just a prelude, and at-rule blocks, such as {{cssxref("@keyframes")}}, {{cssxref("@font-face")}}, and also `@layer`, that contain a body of declarations. These blocks are generally multi-statement and referred to as multi-line, even though they can be illegibly declared with no line-breaks. + +Once an at-rule is started with the `@`, nothing is invalid from the parser's standpoint; it's all part of the at-rule's prelude. The semicolon (`;`) ends the at-rule immediately for single line at-rules. If there is an open curly brace (`{`), this informs the browser where the completed at-rule prelude ends and the at-rule's body starts. For these multi-line at-rules, the parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly-brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. The contents of the at-rule are then interpreted according to the grammar rules for that particular at-rule. + +> **Note:** Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what will invalidate the entire at-rule, if anything. The expected grammar for each at-rule, and how errors are handled, are documented on the individual at-rule page. + +For example, if an `@import` occurs after any other CSS declarations, other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. A `@layer` statement, which can be declared either as a prelude or contain a body of declarations, will always create at least an anonymous layer. If there is an body of declarations, the handling of any error depends on what the error is. The user-agent won't fail, but if the error was a missing closing curly-brace, the rest of the stylesheet will be assumed to be in the cascade layer defined in the at-rules prelude. This is a developer mistake, but not a error that can be noticed and ignored by the parser. + +### Errors in selector lists + +There are many ways you might make a mistake writing a selector, but only invalid selectors cause [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list) issues. + +If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element that doesn't exist, that is an author mistake, not an error the parser needs to handle. If, however, you have a typo in a pseudo-class or pseudo-element, that may create an invalid selector, which is an error the parser will notice. + +If a selector list contains any invalid selectors, it creates an [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list), and the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is()")}} and {{cssxref(":where()")}} pseudo-classes, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list), the selector list will not be invalidated. There is also an [exception for -webkit- prefixed pseudo-elements](#webkit-exception). + +If a selector list contains any invalid selectors outside of an `:is()` or `:where()`, that single unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The user-agent will look for the closing curly-brace and continue parsing again from there. + +#### Webkit exception + +Due to legacy issues with the overuse of browser prefixes in selectors (and property names), to prevent the invalidation of selector lists, browsers treat all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) whose beginning with a `-webkit-` prefix, case-insensitive, that don't end with `()`, as valid. + +This means that `::-webkit-works-only-in-samsung` will not invalidate a selector list no matter the browser. In such cases, the pseudo-element may not be recognized or supported by the browser, but if a `-webkit-` prefixed pseudo-element selector is not recognized, it won't match anything but the entire declaration block will not fail because of it. On the other hand, the selector `::-webkit-works()` ends in a function notation, and will invalidate the selector list and make the browser ignore the entire selector block. + +### Errors within CSS declaration blocks + +When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parsese, or interprets, a list of declarations, unknown syntax at any point causes the user-agent's parser to discard the declaration it is currently parsing, and continue parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. + +The parser seeks forward until it finds a semicolon (or the end of the block). It then starts fresh, trying to parse a declaration again. This example contains an error. The parser ignores the error (and the comments), seeking forward until it encounters a semi-colon, then restarts parsing: + +```css-nolint bad +p { +/* invalid due to missing semi-colon */ + border-color: red + background-color: green; + +/* valid, though it is likely a mistake */ + border-width: 100vh; +} +``` + +The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last declaration in the block. The property missing the semi-colon is ignored, as is the pair following it, as the browser only continues parsing after a semi-colon or closing bracket is encountered. In the above CSS, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. + +The parser ignores the property with a invalid value, and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is valid, it will be parsed and applied to the elements matching the selector. + +### Document end + +If a stylesheet — be it an external style sheet, CSS within a HTML {{HTMLElement("style")}} element, or an inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. + +If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. Failing to properly close CSS statements doesn't necessarily make the statements invalid. + +Do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain, and ensures that the browser parses the CSS you intended. + +### Grammar check + +After each declaration, style rule, at-rule, etc. is parsed, the user agent checks to make sure the grammar is the expected grammar for that declaration. For example, if a property value is of the wrong data type or if a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid, and gets ignored. + +> **Note:** If a comment is with `/*` but not closed, any and all CSS encountered until the closing comment `*/` is found will be treated as a comment. Forgetting to close a comment may not make your CSS invalid, but it will make cause the CSS inside the comment to be ignored. + +## See also + +- [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module +- [Syntax](/en-US/docs/Web/CSS/Syntax) guide +- [Value definition syntax](/en-US/docs/Web/CSS/Value_definition_syntax) From e9bffa8e135a2d6823a1d7359154af46db297438 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Tue, 5 Dec 2023 00:42:05 -0800 Subject: [PATCH 02/43] deprecate @charset and list as a rule not at-rule --- files/en-us/web/css/@charset/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/files/en-us/web/css/@charset/index.md b/files/en-us/web/css/@charset/index.md index 1dc70ae3725a5e2..2898933455be027 100644 --- a/files/en-us/web/css/@charset/index.md +++ b/files/en-us/web/css/@charset/index.md @@ -7,7 +7,9 @@ browser-compat: css.at-rules.charset {{CSSRef}} -The **`@charset`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/At-rule) specifies the character encoding used in the style sheet. It must be the first element in the style sheet and not be preceded by any character; as it is not a [nested statement](/en-US/docs/Web/CSS/Syntax#nested_statements), it cannot be used inside [conditional group at-rules](/en-US/docs/Web/CSS/At-rule#conditional_group_rules). If several `@charset` at-rules are defined, only the first one is used, and it cannot be used inside a `style` attribute on an HTML element or inside the {{ HTMLElement("style") }} element where the character set of the HTML page is relevant. +The **`@charset`** [CSS](/en-US/docs/Web/CSS) rule specifies the character encoding used in the style sheet. Although the first character is the `@` symbol, it is not an [at-rule](/en-US/docs/Web/CSS/At-rule). The [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module deprecates this rule, defining it as an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked. + +The `@charset` rule must be the first element in the style sheet and not be preceded by any character; as it is not a [nested statement](/en-US/docs/Web/CSS/Syntax#nested_statements), it cannot be used inside [conditional group at-rules](/en-US/docs/Web/CSS/At-rule#conditional_group_rules). If several `@charset` at-rules are defined, only the first one is used, and it cannot be used inside a `style` attribute on an HTML element or inside the {{ HTMLElement("style") }} element where the character set of the HTML page is relevant. ```css @charset "utf-8"; From d5f17330b34541a6b74c812a88a5274f441baf4a Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Tue, 5 Dec 2023 00:42:40 -0800 Subject: [PATCH 03/43] Define character encoding --- files/en-us/web/css/custom-ident/index.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/css/custom-ident/index.md b/files/en-us/web/css/custom-ident/index.md index a6261b6ee58ffe6..041fad7aa76cb43 100644 --- a/files/en-us/web/css/custom-ident/index.md +++ b/files/en-us/web/css/custom-ident/index.md @@ -21,10 +21,27 @@ The syntax of `` is similar to CSS identifiers (such as property n - any decimal digit (`0` to `9`), - a hyphen (`-`), - an underscore (`_`), -- an escaped character (preceded by a backslash, `\`), +- an [escaped character](#escaping-characters) (preceded by a backslash, `\`), - a [Unicode](https://en.wikipedia.org/wiki/Unicode) character (in the format of a backslash, `\`, followed by one to six hexadecimal digits, representing its Unicode code point) -Note that `id1`, `Id1`, `iD1` and `ID1` are all different identifiers as they are [case-sensitive](https://en.wikipedia.org/wiki/Case_sensitivity). On the other hand, as there are several ways to escape a character, `toto\?` and `toto\3F` are the same identifiers. +Note that `id1`, `Id1`, `iD1` and `ID1` are all different identifiers as they are [case-sensitive](https://en.wikipedia.org/wiki/Case_sensitivity). + +### Escaping characters + +Any Unicode code point can be included as part of a `` or quoted {{cssxref("string")}} by escaping it. + +In CSS, there are several ways to escape a character. Escape sequences start with a backslash (`\`), and continue with: + +- One to six hex (`ABCDEF0123456789`) digits. The hex digits can optionally be followed white space. The hex escape sequence gets replaced by the Unicode code point whose value is given by those digits. The whitespace allows the sequences to be followed by actual hex digits (versus replaced ones). +- Any Unicode code point that is not a hex digit or a newline character. + +Examples: + +- "&B" can be written as `\26 B` and `\000026B`. +- "hi.there" can be written as `hi\.there` and `hi\002Ethere`. +- "toto?" can be written as`toto\?`, `toto\3F`, or `toto\00003F` + +To include actual white space after an escape sequence, include two white spaces in the escape sequence . ### Forbidden values From bddc9a2a9d83bf2cf3781df49827717f4418c365 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Tue, 5 Dec 2023 00:43:55 -0800 Subject: [PATCH 04/43] New page: error handling --- files/en-us/web/css/css_syntax/error_handling/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index d2c7a2cb0df6dd1..526ed523ab80842 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -69,7 +69,7 @@ The reason the first declaration in this selector block is invalid is because th The parser ignores the property with a invalid value, and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is valid, it will be parsed and applied to the elements matching the selector. -### Document end +### Auto-closed endings If a stylesheet — be it an external style sheet, CSS within a HTML {{HTMLElement("style")}} element, or an inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. @@ -77,12 +77,12 @@ If the content between the last semi-colon and the end of the stylesheet is vali Do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain, and ensures that the browser parses the CSS you intended. +> **Note:** If a comment is with `/*` but not closed, any and all CSS encountered until the closing comment `*/` is found will be treated as a comment. Forgetting to close a comment may not make your CSS invalid, but it will make cause the CSS inside the comment to be ignored. + ### Grammar check After each declaration, style rule, at-rule, etc. is parsed, the user agent checks to make sure the grammar is the expected grammar for that declaration. For example, if a property value is of the wrong data type or if a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid, and gets ignored. -> **Note:** If a comment is with `/*` but not closed, any and all CSS encountered until the closing comment `*/` is found will be treated as a comment. Forgetting to close a comment may not make your CSS invalid, but it will make cause the CSS inside the comment to be ignored. - ## See also - [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module From 9ff78fceb16f20177d16ce801f0fc625cf4e1bb1 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Tue, 5 Dec 2023 00:44:43 -0800 Subject: [PATCH 05/43] New page: css syntax module --- files/en-us/web/css/css_syntax/index.md | 95 +++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 files/en-us/web/css/css_syntax/index.md diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md new file mode 100644 index 000000000000000..a42db32f24c1ece --- /dev/null +++ b/files/en-us/web/css/css_syntax/index.md @@ -0,0 +1,95 @@ +--- +title: CSS syntax +slug: Web/CSS/CSS_syntax +page-type: css-module +spec-urls: https://drafts.csswg.org/css-syntax +--- + +{{CSSRef}} + +The **CSS syntax** module describes, in general terms, the structure and syntax of cascading stylesheets, or CSS. It defines CSS as the language for describing the rendering of structured documents (such as HTML and XML), whether on the web or anywhere else. + +The CSS syntax module doesn't define any properties, {{cssxref("css_types", "data types")}}, {{cssxref("css_functions", "functions")}}, or {{cssxref("at-rule", "at-rules")}}. Rather, this module defines how all of these features are defined and how user agents should parse CSS. + +The module explicitly states that {{cssxref("@charset")}} is not an actual at-rule, but rather an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked. + +## Reference + +### Key concepts and definitions + +- [`` notation]() +- [declaration](/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration) +- {{glossary("CSS_Descriptor", "descriptor")}} +- [comments](/en-US/docs/Web/CSS/Comments) +- [declaration block](/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration_Block) +- [escaping](/en-US/docs/Web/CSS/custom-ident#escaping_characters) +- [function](/en-US/docs/Web/CSS/CSS_Functions) +- [invalid](/en-US/docs/Web/CSS/CSS_syntax/error_handling) +- {{glossary("parse")}} +- [rule](/en-US/docs/Web/API/CSSRule) +- {{cssxref("at-rule")}} +- [style rule](/en-US/docs/Web/API/CSSStyleRule) +- {{glossary("stylesheet")}} +- {{glossary("whitespace")}} + +## Guides + +- [Syntax](/en-US/docs/Web/CSS/Syntax) + + - : Overview of CSS syntax, including CSS declarations, declaration blocks, rulesets, and statements. + +- [Value definition syntax](/en-US/docs/Web/CSS/Value_definition_syntax) + + - : The formal grammar for defining valid values for CSS properties and functions, along with semantic constraints. A guide to CSS component value types, combinators, and multipliers. + +- [CSS syntax error handling](/en-US/docs/Web/CSS/CSS_syntax/error_handling) + - : Overview of how the user-agent handles + +## Related Concepts + +[CSS selectors](/en-US/docs/Web/CSS/CSS_selectors) module + +- [specificity](/en-US/docs/Web/CSS/Specificity) + +[CSS Cascade](/en-US/docs/Web/CSS/CSS_cascade) module + +- {{cssxref("@import")}} at-rule +- {{cssxref("important")}} flag +- [Initial values](/en-US/docs/Web/CSS/initial_value) +- [Computed values](/en-US/docs/Web/CSS/computed_value) +- [Used values](/en-US/docs/Web/CSS/used_value) +- [Actual values](/en-US/docs/Web/CSS/actual_value) +- [inheritance](/en-US/docs/Web/CSS/Inheritance) +- {{Glossary("Property/CSS", "property")}} + +[CSS Custom Properties for Cascading Variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module + +- [custom property (`--*`)](/en-US/docs/Web/CSS/--*) +- {{cssxref("var()")}} + +[CSS conditional rules](/en-US/docs/Web/CSS/CSS_conditional_rules) module + +- {{cssxref("@media")}} +- {{cssxref("@supports")}} + +[CSS Object Model (CSSOM)](/en-US/docs/Web/API/CSS_Object_Model) module + +- {{domxref("CSSValue.cssText", "cssText")}} +- {{domxref("CSSStyleSheet.insertRule()", "insertRule(rule)")}} +- {{domxref("CSSStyleSheet.replace()", "replace(text)")}} + +[WHATWG](/en-US/docs/Glossary/WHATWG) specification + +- {{HTMLElement("style")}} +- {{HTMLElement("link")}} +- [`class`](/en-US/docs/Web/HTML/Global_attributes/class) attribute +- [`rel`](/en-US/docs/Web/HTML/Attributes/rel#stylesheet) attribute + +## Specifications + +{{Specifications}} + +## See also + +- [CSS selectors](/en-US/docs/Web/CSS/CSS_selectors) module +- [CSS values & units](/en-US/docs/Web/CSS/CSS_values_and_units) module From 1c099d579ae970f3a38457123d79ea918bb32653 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Tue, 5 Dec 2023 00:45:20 -0800 Subject: [PATCH 06/43] delete charset module. move to syntax module --- files/en-us/_redirects.txt | 1 + files/en-us/_wikihistory.json | 8 ++++---- files/en-us/web/css/css_charsets/index.md | 24 ----------------------- 3 files changed, 5 insertions(+), 28 deletions(-) delete mode 100644 files/en-us/web/css/css_charsets/index.md diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index cee4b2fb43f8f4e..019f8af9b6bf224 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -11480,6 +11480,7 @@ /en-US/docs/Web/CSS/CSS_User_Interface /en-US/docs/Web/CSS/CSS_basic_user_interface /en-US/docs/Web/CSS/CSS_Variables /en-US/docs/Web/CSS/CSS_cascading_variables /en-US/docs/Web/CSS/CSS_Viewport /en-US/docs/Web/CSS +/en-US/docs/Web/CSS/CSS_charsets /en-US/docs/Web/CSS/CSS_syntax /en-US/docs/Web/CSS/CSS_descriptor_definition /en-US/docs/Web/CSS /en-US/docs/Web/CSS/CSS_flex-wrap /en-US/docs/Web/CSS/flex-wrap /en-US/docs/Web/CSS/CSS_grid_layout/Layout_using_line-based_placement /en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_line-based_placement diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index fc98aa44310ee36..cb82251c3fa4916 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -77124,10 +77124,6 @@ "modified": "2020-07-07T12:03:44.891Z", "contributors": ["wbamberg", "mfluehr"] }, - "Web/CSS/CSS_charsets": { - "modified": "2020-10-15T21:38:35.251Z", - "contributors": ["wbamberg", "fscholz", "mfluehr", "Sebastianz", "teoli"] - }, "Web/CSS/CSS_colors": { "modified": "2020-12-02T11:04:05.642Z", "contributors": ["peterbe", "wbamberg", "fscholz", "Sheppy", "mfluehr"] @@ -78500,6 +78496,10 @@ "modified": "2020-04-27T22:31:21.929Z", "contributors": ["ExE-Boss", "mfuji09", "rachelandrew"] }, + "Web/CSS/CSS_syntax": { + "modified": "2020-10-15T21:38:35.251Z", + "contributors": ["wbamberg", "fscholz", "mfluehr", "Sebastianz", "teoli"] + }, "Web/CSS/CSS_table": { "modified": "2020-07-07T12:26:58.542Z", "contributors": ["wbamberg", "fscholz", "mfluehr", "Sebastianz", "teoli"] diff --git a/files/en-us/web/css/css_charsets/index.md b/files/en-us/web/css/css_charsets/index.md deleted file mode 100644 index d730e25dc51d1ca..000000000000000 --- a/files/en-us/web/css/css_charsets/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: CSS charsets -slug: Web/CSS/CSS_charsets -page-type: css-module -browser-compat: css.at-rules.charset ---- - -{{CSSRef}} - -The **CSS charsets** module lets you specify the character set used in the style sheet. - -## Reference - -### At-rules - -- {{cssxref("@charset")}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} From df627d9a56792803262efb1227bbeec2b97d7c72 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Tue, 5 Dec 2023 11:57:25 -0800 Subject: [PATCH 07/43] still supported --- files/en-us/web/css/@charset/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/css/@charset/index.md b/files/en-us/web/css/@charset/index.md index 2898933455be027..e41f817b1f0e230 100644 --- a/files/en-us/web/css/@charset/index.md +++ b/files/en-us/web/css/@charset/index.md @@ -7,7 +7,7 @@ browser-compat: css.at-rules.charset {{CSSRef}} -The **`@charset`** [CSS](/en-US/docs/Web/CSS) rule specifies the character encoding used in the style sheet. Although the first character is the `@` symbol, it is not an [at-rule](/en-US/docs/Web/CSS/At-rule). The [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module deprecates this rule, defining it as an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked. +The **`@charset`** [CSS](/en-US/docs/Web/CSS) rule specifies the character encoding used in the style sheet. Although the first character is the `@` symbol, it is not an [at-rule](/en-US/docs/Web/CSS/At-rule). The [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module deprecates this rule, defining it as an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked, but it is [fully supported in all browsers](#browser-compatibility). The `@charset` rule must be the first element in the style sheet and not be preceded by any character; as it is not a [nested statement](/en-US/docs/Web/CSS/Syntax#nested_statements), it cannot be used inside [conditional group at-rules](/en-US/docs/Web/CSS/At-rule#conditional_group_rules). If several `@charset` at-rules are defined, only the first one is used, and it cannot be used inside a `style` attribute on an HTML element or inside the {{ HTMLElement("style") }} element where the character set of the HTML page is relevant. From 9b2da17592688cec495ae084826aacc690ecb7dd Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 6 Dec 2023 00:37:00 -0800 Subject: [PATCH 08/43] table of contents --- .../web/css/css_syntax/error_handling/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 526ed523ab80842..3752e9e6969aa91 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -6,17 +6,17 @@ page-type: guide {{CSSRef}} -When an error is made in CSS, instead of [throwing an error](/en-US/docs/Web/JavaScript/Reference/Errors) like in JavaScript, the browser will gracefully recover, skipping over the invalid content. While the user agent won't alert you to CSS errors, the user agent won't fail either. This is a feature of CSS, not a bug. +When an error is made in CSS, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser will gracefully recover, skipping over the invalid content. While the user agent won't alert you to CSS errors, the user agent won't fail either. This is a feature of CSS, not a bug. -In CSS, when an error is made, the user-agent parser ignores the lines containting the errors, discarding the minimum amount of content before returning to parsing as normal. This error-recovery is done because, as new features are added to CSS, a browser may not recognize new features and will simply discard the line with the content with what it may currently view as error. This enables adding new features to CSS without worrying that anything, other than the new feature, is broken in older browsers. It also enables including both old and new syntax, in that order, so the old syntax is rendered until the new syntax becomes parsed as valid. +In CSS, when an error is made, the user-agent's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to parsing as normal. This error recovery is done because, as new features are added to CSS, a browser may not recognize new features and will simply discard the line with the content with what it may currently view as an error. This enables adding new features to CSS without worrying that anything, other than the new feature, is broken in older browsers. It also enables including both old and new syntax, in that order, so the old syntax is rendered until the new syntax becomes parsed as valid. Because user agents ignore CSS errors, the valid fallback CSS doesn't get overwritten by perceived as invalid new CSS. -The type of content that gets ignored, depends on the type of error. For example, +The type and amount of CSS that gets ignored depends on the type of error. For example, -- For errors in at-rules, whether a single line or the entire at-rule fails depends on the at-rule and the type of error. -- If the error is an invalid selector, the entire declaration block is ignored. -- If a semi-colon is omitted between property declarations, the missing semi-colon causes an invalid value, so the declaration is ignored. -- If the error is a property name or value, such as an unrecognized property name or invalid data type, the declaration is ignored. -- If the error is a missing end-bracket, what gets ignored depends on whether the user-agent can parse the error as nested CSS. +- For [errors in at-rules](#at-rule-errors), whether a single line or the entire at-rule fails depends on the at-rule and the type of error. +- If the error is an [invalid selector](#errors-in-selector-lists), the entire declaration block is ignored. +- If a semi-colon is omitted between property declarations, the [missing semi-colon](#errors-within-css-declaration-blocks) causes an invalid value, so the declaration is ignored. +- If the [error is a property name or value](#errors-within-css-declaration-blocks), such as an unrecognized property name or invalid data type, just that property/value declaration is ignored. +- If the issue is a [missing end-bracket](#auto-closed-endings), what gets ignored, if anything, depends on whether the user-agent can parse the error as nested CSS. After each declaration, style rule, at-rule, etc. is parsed, the user agent checks the parsed content against its expected grammar for that construct. If it does not match the expected grammar for that construct, it is invalid, and is ignored. From bd5f7526ed578624f4aaa783d33cf8dbd9dfce93 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 6 Dec 2023 01:13:29 -0800 Subject: [PATCH 09/43] better grammar --- files/en-us/web/css/css_syntax/error_handling/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 3752e9e6969aa91..007b72d6e6e411e 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -18,19 +18,19 @@ The type and amount of CSS that gets ignored depends on the type of error. For e - If the [error is a property name or value](#errors-within-css-declaration-blocks), such as an unrecognized property name or invalid data type, just that property/value declaration is ignored. - If the issue is a [missing end-bracket](#auto-closed-endings), what gets ignored, if anything, depends on whether the user-agent can parse the error as nested CSS. -After each declaration, style rule, at-rule, etc. is parsed, the user agent checks the parsed content against its expected grammar for that construct. If it does not match the expected grammar for that construct, it is invalid, and is ignored. +After each declaration, style rule, at-rule, etc. is parsed, the user agent checks the parsed content against its expected [grammar](#grammar-check) for that construct. If it does not match the expected grammar for that construct, it is invalid and is ignored. ## CSS parser errors ### At-rule errors -The `@`, known in the CSS specifications as an ``, indicates the beginning of an at-rule. CSS includes single line at-rules, such as such as {{cssxref("@import")}} or {{cssxref("@layer")}} that contain just a prelude, and at-rule blocks, such as {{cssxref("@keyframes")}}, {{cssxref("@font-face")}}, and also `@layer`, that contain a body of declarations. These blocks are generally multi-statement and referred to as multi-line, even though they can be illegibly declared with no line-breaks. +The `@`, known in the CSS specifications as an ``, indicates the beginning of an {{cssxref("at-rule")}}. CSS includes at-rules that contain just a prelude, like {{cssxref("@import")}} or some {{cssxref("@layer")}} declarations, and at-rule blocks that contain a body of declarations, like {{cssxref("@keyframes")}}, {{cssxref("@font-face")}}, and `@layer` declarations that include styles blocks. These at-rule blocks are generally multi-statement and referred to as multi-line, even though they can be declared with no line breaks. -Once an at-rule is started with the `@`, nothing is invalid from the parser's standpoint; it's all part of the at-rule's prelude. The semicolon (`;`) ends the at-rule immediately for single line at-rules. If there is an open curly brace (`{`), this informs the browser where the completed at-rule prelude ends and the at-rule's body starts. For these multi-line at-rules, the parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly-brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. The contents of the at-rule are then interpreted according to the grammar rules for that particular at-rule. +Once an at-rule is started with the `@`, nothing is invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or opening curly brace (`{`) is part of the at-rule's prelude. The semicolon ends the at-rule immediately for single-line at-rules. If there is an open curly brace, this informs the browser where the completed at-rule prelude ends and the at-rule's body starts. For these multi-line at-rules, the parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. The contents of the at-rule are then interpreted according to the grammar rules for that particular at-rule. -> **Note:** Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what will invalidate the entire at-rule, if anything. The expected grammar for each at-rule, and how errors are handled, are documented on the individual at-rule page. +> **Note:** Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what will invalidate the entire at-rule, if anything. The expected grammar for each at-rule, and how errors are handled, are documented on each individual at-rule page. -For example, if an `@import` occurs after any other CSS declarations, other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. A `@layer` statement, which can be declared either as a prelude or contain a body of declarations, will always create at least an anonymous layer. If there is an body of declarations, the handling of any error depends on what the error is. The user-agent won't fail, but if the error was a missing closing curly-brace, the rest of the stylesheet will be assumed to be in the cascade layer defined in the at-rules prelude. This is a developer mistake, but not a error that can be noticed and ignored by the parser. +For example, if an `@import` occurs after any other CSS declarations, other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. A `@layer` statement, which can be declared either as a prelude or contain a body of declarations, will always create at least an anonymous layer. If there is a declaration body, the handling of any error depends on the error. The user-agent won't fail; rather, invalid CSS is ignored. If the error is a missing closing curly brace, you have a logic error not a CSS error. In the case of a missing closing brace in an `@layer`, the styles will be assumed to be in the cascade layer defined in the at-rule's prelude. This is a developer mistake, a logic error. The CSS is considered valid; nothing is invalid, so nothing is ignored by the parser. ### Errors in selector lists From 10d57b21ba432e160f4bdf986d09e9fc53a23764 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 6 Dec 2023 01:15:58 -0800 Subject: [PATCH 10/43] better grammar --- files/en-us/web/css/css_syntax/error_handling/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 007b72d6e6e411e..efe774e36b38a65 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -36,9 +36,9 @@ For example, if an `@import` occurs after any other CSS declarations, other than There are many ways you might make a mistake writing a selector, but only invalid selectors cause [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list) issues. -If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element that doesn't exist, that is an author mistake, not an error the parser needs to handle. If, however, you have a typo in a pseudo-class or pseudo-element, that may create an invalid selector, which is an error the parser will notice. +If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element that doesn't exist, it may be a logic error, but not an error the parser needs to handle. If, however, you have a typo in a pseudo-class or pseudo-element, that may create an invalid selector, which is an error the parser will notice. -If a selector list contains any invalid selectors, it creates an [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list), and the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is()")}} and {{cssxref(":where()")}} pseudo-classes, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list), the selector list will not be invalidated. There is also an [exception for -webkit- prefixed pseudo-elements](#webkit-exception). +If a selector list contains any invalid selectors, it creates an [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list), and the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} and {{cssxref(":where")}} pseudo-classes, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list), the selector list will not be invalidated. There is also an [exception for -webkit- prefixed pseudo-elements](#webkit-exception). If a selector list contains any invalid selectors outside of an `:is()` or `:where()`, that single unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The user-agent will look for the closing curly-brace and continue parsing again from there. From 2d832cf0e458f108f13e1b92f0155a39195638cf Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 6 Dec 2023 01:38:21 -0800 Subject: [PATCH 11/43] better grammar --- .../web/css/css_syntax/error_handling/index.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index efe774e36b38a65..d5643d6bc67a5bc 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -38,21 +38,23 @@ There are many ways you might make a mistake writing a selector, but only invali If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element that doesn't exist, it may be a logic error, but not an error the parser needs to handle. If, however, you have a typo in a pseudo-class or pseudo-element, that may create an invalid selector, which is an error the parser will notice. -If a selector list contains any invalid selectors, it creates an [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list), and the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} and {{cssxref(":where")}} pseudo-classes, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list), the selector list will not be invalidated. There is also an [exception for -webkit- prefixed pseudo-elements](#webkit-exception). +If a selector list contains any invalid selectors, it creates an [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list), and the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} and {{cssxref(":where")}} pseudo-classes, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list), the selector list will not be invalidated. There is also an [exception for -webkit-]](#webkit-exception) prefixed pseudo-elements. -If a selector list contains any invalid selectors outside of an `:is()` or `:where()`, that single unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The user-agent will look for the closing curly-brace and continue parsing again from there. +If a selector list contains any invalid selectors outside of an `:is()` or `:where()`, that single unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The user-agent will look for the closing curly brace and will continue parsing again from that point on. #### Webkit exception -Due to legacy issues with the overuse of browser prefixes in selectors (and property names), to prevent the invalidation of selector lists, browsers treat all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) whose beginning with a `-webkit-` prefix, case-insensitive, that don't end with `()`, as valid. +Due to legacy issues with the overuse of browser prefixes in selectors (and property names), to prevent the invalidation of selector lists, browsers treat all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a `-webkit-` prefix, case-insensitive, and that don't end with `()`, as valid. -This means that `::-webkit-works-only-in-samsung` will not invalidate a selector list no matter the browser. In such cases, the pseudo-element may not be recognized or supported by the browser, but if a `-webkit-` prefixed pseudo-element selector is not recognized, it won't match anything but the entire declaration block will not fail because of it. On the other hand, the selector `::-webkit-works()` ends in a function notation, and will invalidate the selector list and make the browser ignore the entire selector block. +This means that `::-webkit-works-only-in-samsung` will not invalidate a selector list no matter the browser. In such cases, the pseudo-element may not be recognized or supported by the browser, but if a `-webkit-` prefixed pseudo-element will not cause the entire selector list and it's associated style block to be ignored. On the other hand, the unknown prefixed selector with a function notation `::-webkit-imaginary-function()` will invalidate the entire selector list and the browser will ignore the entire selector block. ### Errors within CSS declaration blocks -When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parsese, or interprets, a list of declarations, unknown syntax at any point causes the user-agent's parser to discard the declaration it is currently parsing, and continue parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. +When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parses, or interprets, a list of declarations, unknown syntax at any point causes the user-agent's parser to discard just that rule and continue parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. -The parser seeks forward until it finds a semicolon (or the end of the block). It then starts fresh, trying to parse a declaration again. This example contains an error. The parser ignores the error (and the comments), seeking forward until it encounters a semi-colon, then restarts parsing: +The parser seeks forward until it finds a semicolon (or the end of the block). It then starts fresh, trying to parse a declaration again. + +This example contains an error. The parser ignores the error (and the comments), seeking forward until it encounters a semi-colon, then restarts parsing: ```css-nolint bad p { From 3afcdbdcd8ae4a9261b6b047bfa5f264fa664da6 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 6 Dec 2023 01:40:46 -0800 Subject: [PATCH 12/43] better grammar --- files/en-us/web/css/css_syntax/error_handling/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index d5643d6bc67a5bc..c4be7dfb0373b9e 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -73,7 +73,7 @@ The parser ignores the property with a invalid value, and starts parsing again a ### Auto-closed endings -If a stylesheet — be it an external style sheet, CSS within a HTML {{HTMLElement("style")}} element, or an inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. +If a stylesheet — be it an external style sheet, CSS within an HTML {{HTMLElement("style")}} element, or an inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. Failing to properly close CSS statements doesn't necessarily make the statements invalid. From e1424fbace4d95f3254d30203e7fd8be9d71cdb6 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Thu, 7 Dec 2023 15:14:02 -0800 Subject: [PATCH 13/43] Apply suggestions from code review Co-authored-by: Dipika Bhattacharya --- files/en-us/web/css/css_syntax/index.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md index a42db32f24c1ece..fc4af083c7c2318 100644 --- a/files/en-us/web/css/css_syntax/index.md +++ b/files/en-us/web/css/css_syntax/index.md @@ -7,11 +7,11 @@ spec-urls: https://drafts.csswg.org/css-syntax {{CSSRef}} -The **CSS syntax** module describes, in general terms, the structure and syntax of cascading stylesheets, or CSS. It defines CSS as the language for describing the rendering of structured documents (such as HTML and XML), whether on the web or anywhere else. +The **CSS syntax** module describes, in general terms, the structure and syntax of cascading stylesheets, or CSS. It defines CSS as the language for describing the rendering of structured documents (such as HTML and XML), on the web and elsewhere. -The CSS syntax module doesn't define any properties, {{cssxref("css_types", "data types")}}, {{cssxref("css_functions", "functions")}}, or {{cssxref("at-rule", "at-rules")}}. Rather, this module defines how all of these features are defined and how user agents should parse CSS. +This module doesn't define any properties, {{cssxref("css_types", "data types")}}, {{cssxref("css_functions", "functions")}}, or {{cssxref("at-rule", "at-rules")}}. Rather, it elaborates on how all of these features should be defined and how user agents should parse CSS. -The module explicitly states that {{cssxref("@charset")}} is not an actual at-rule, but rather an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked. +The module explicitly states that {{cssxref("@charset")}} is not an actual at-rule, but rather an unrecognized legacy rule that should be omitted when a stylesheet is grammar-checked. ## Reference @@ -40,18 +40,18 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru - [Value definition syntax](/en-US/docs/Web/CSS/Value_definition_syntax) - - : The formal grammar for defining valid values for CSS properties and functions, along with semantic constraints. A guide to CSS component value types, combinators, and multipliers. + - : The formal grammar for defining valid values for CSS properties and functions, along with semantic constraints. A guide for understanding CSS component value types, combinators, and multipliers. - [CSS syntax error handling](/en-US/docs/Web/CSS/CSS_syntax/error_handling) - : Overview of how the user-agent handles -## Related Concepts +## Related concepts -[CSS selectors](/en-US/docs/Web/CSS/CSS_selectors) module +[CSS selectors](/en-US/docs/Web/CSS/CSS_selectors) module: - [specificity](/en-US/docs/Web/CSS/Specificity) -[CSS Cascade](/en-US/docs/Web/CSS/CSS_cascade) module +[CSS cascade](/en-US/docs/Web/CSS/CSS_cascade) module - {{cssxref("@import")}} at-rule - {{cssxref("important")}} flag @@ -60,12 +60,12 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru - [Used values](/en-US/docs/Web/CSS/used_value) - [Actual values](/en-US/docs/Web/CSS/actual_value) - [inheritance](/en-US/docs/Web/CSS/Inheritance) -- {{Glossary("Property/CSS", "property")}} +- {{Glossary("Property/CSS", "CSS property")}} glossary term -[CSS Custom Properties for Cascading Variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module +[CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module: - [custom property (`--*`)](/en-US/docs/Web/CSS/--*) -- {{cssxref("var()")}} +- {{cssxref("var")}} [CSS conditional rules](/en-US/docs/Web/CSS/CSS_conditional_rules) module @@ -92,4 +92,4 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru ## See also - [CSS selectors](/en-US/docs/Web/CSS/CSS_selectors) module -- [CSS values & units](/en-US/docs/Web/CSS/CSS_values_and_units) module +- [CSS values and units](/en-US/docs/Web/CSS/CSS_Values_and_units) module From 4691893fb45307bafa9a1adb626792cc899a8be9 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Thu, 7 Dec 2023 00:50:59 -0800 Subject: [PATCH 14/43] added a few more notes - prefixes --- .../css/css_syntax/error_handling/index.md | 38 ++++++++++++++++--- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index c4be7dfb0373b9e..cd0dfd6dedd6261 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -38,13 +38,13 @@ There are many ways you might make a mistake writing a selector, but only invali If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element that doesn't exist, it may be a logic error, but not an error the parser needs to handle. If, however, you have a typo in a pseudo-class or pseudo-element, that may create an invalid selector, which is an error the parser will notice. -If a selector list contains any invalid selectors, it creates an [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list), and the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} and {{cssxref(":where")}} pseudo-classes, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list), the selector list will not be invalidated. There is also an [exception for -webkit-]](#webkit-exception) prefixed pseudo-elements. +If a selector list contains any invalid selectors, it is an [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list) and the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-classes, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list) or if the unknown selectors is a [`-webkit-` prefixed pseudo-element](#webkit-exception), only the unknown selector is ignored as not matching anything. The selector list is not be invalidated.. -If a selector list contains any invalid selectors outside of an `:is()` or `:where()`, that single unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The user-agent will look for the closing curly brace and will continue parsing again from that point on. +If a selector list contains any invalid selectors outside of these exception, a single invalid or unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The user-agent will look for the closing curly brace and will continue parsing again from that point on. #### Webkit exception -Due to legacy issues with the overuse of browser prefixes in selectors (and property names), to prevent the invalidation of selector lists, browsers treat all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a `-webkit-` prefix, case-insensitive, and that don't end with `()`, as valid. +Due to legacy issues with the overuse of browser prefixes in selectors (and [property names and values](#vendor-prefixes)), to prevent the invalidation of selector lists, browsers treat all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a `-webkit-` prefix, case-insensitive, and that don't end with `()`, as valid. This means that `::-webkit-works-only-in-samsung` will not invalidate a selector list no matter the browser. In such cases, the pseudo-element may not be recognized or supported by the browser, but if a `-webkit-` prefixed pseudo-element will not cause the entire selector list and it's associated style block to be ignored. On the other hand, the unknown prefixed selector with a function notation `::-webkit-imaginary-function()` will invalidate the entire selector list and the browser will ignore the entire selector block. @@ -71,13 +71,41 @@ The reason the first declaration in this selector block is invalid is because th The parser ignores the property with a invalid value, and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is valid, it will be parsed and applied to the elements matching the selector. +#### Vendor prefixes + +Vendor-prefixed property names and property values, when not understood by a browser, are ignored. Only the single rule containing the invalid property or value is ignored. The parser looks for the next semi-colon or closing curly brace and then continues parsing from there. + +You may come across legacy CSS that looks like the following: + +```css example-bad +/* prefixed values */ +.wrapper { + display: -webkit-box; + display: -webkit-flex; + display: -ms-flexbox; + display: flex; +} +/* prefixed properties */ +.rounded { + -webkit-border-radius: 50%; + -moz-border-radius: 50%; + -ms-border-radius: 50%; + -o-border-radius: 50%; + border-radius: 50%; +} +``` + +The valid CSS rules are the last ones in each declaration block above. The parser ignores the rules it doesn't understand as invalid. If the user agent does understand one of the prefixed rules, as all browsers understand `display: flex;` and `border-radius: 50%;`, the values in the last, valid declaration are used, not because they are the valid ones, but rather due to the [cascade](/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#source_order) [order of appearance](/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) rule. + +> **Note:** Avoid including prefixed properties or property values. If you must, declare the prefixed values before the valid, non-prefixed standard compliant property and value. + ### Auto-closed endings -If a stylesheet — be it an external style sheet, CSS within an HTML {{HTMLElement("style")}} element, or an inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. +If a stylesheet — be it an external style sheet, selector blocks within an HTML {{HTMLElement("style")}} element, or inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. Failing to properly close CSS statements doesn't necessarily make the statements invalid. -Do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain, and ensures that the browser parses the CSS you intended. +> **Note:** Do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS you intended. > **Note:** If a comment is with `/*` but not closed, any and all CSS encountered until the closing comment `*/` is found will be treated as a comment. Forgetting to close a comment may not make your CSS invalid, but it will make cause the CSS inside the comment to be ignored. From 245d12673fa3adfa23c301179c4854a050649475 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Thu, 7 Dec 2023 15:53:52 -0800 Subject: [PATCH 15/43] edits per review --- files/en-us/web/css/css_syntax/index.md | 58 +++++++++++++------------ 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md index fc4af083c7c2318..c1440e4c3daa4a4 100644 --- a/files/en-us/web/css/css_syntax/index.md +++ b/files/en-us/web/css/css_syntax/index.md @@ -15,20 +15,21 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru ## Reference -### Key concepts and definitions - -- [`` notation]() -- [declaration](/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration) -- {{glossary("CSS_Descriptor", "descriptor")}} -- [comments](/en-US/docs/Web/CSS/Comments) -- [declaration block](/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration_Block) -- [escaping](/en-US/docs/Web/CSS/custom-ident#escaping_characters) -- [function](/en-US/docs/Web/CSS/CSS_Functions) -- [invalid](/en-US/docs/Web/CSS/CSS_syntax/error_handling) -- {{glossary("parse")}} -- [rule](/en-US/docs/Web/API/CSSRule) +### Key concepts + - {{cssxref("at-rule")}} +- [character escaping](/en-US/docs/Web/CSS/custom-ident#escaping_characters) +- [CSS comments](/en-US/docs/Web/CSS/Comments) +- [CSS declaration](/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration) +- [CSS declaration block](/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration_Block) +- [CSS function](/en-US/docs/Web/CSS/CSS_Functions) +- [invalid](/en-US/docs/Web/CSS/CSS_syntax/error_handling) - [style rule](/en-US/docs/Web/API/CSSStyleRule) + +## Glossary terms + +- {{glossary("CSS_Descriptor", "CSS descriptor")}} +- {{glossary("parse")}} - {{glossary("stylesheet")}} - {{glossary("whitespace")}} @@ -43,15 +44,16 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru - : The formal grammar for defining valid values for CSS properties and functions, along with semantic constraints. A guide for understanding CSS component value types, combinators, and multipliers. - [CSS syntax error handling](/en-US/docs/Web/CSS/CSS_syntax/error_handling) - - : Overview of how the user-agent handles + + - : Overview of how the user-agent handles invalid CSS ## Related concepts [CSS selectors](/en-US/docs/Web/CSS/CSS_selectors) module: -- [specificity](/en-US/docs/Web/CSS/Specificity) +- [CSS specificity](/en-US/docs/Web/CSS/Specificity) -[CSS cascade](/en-US/docs/Web/CSS/CSS_cascade) module +[CSS cascade](/en-US/docs/Web/CSS/CSS_cascade) module: - {{cssxref("@import")}} at-rule - {{cssxref("important")}} flag @@ -59,29 +61,29 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru - [Computed values](/en-US/docs/Web/CSS/computed_value) - [Used values](/en-US/docs/Web/CSS/used_value) - [Actual values](/en-US/docs/Web/CSS/actual_value) -- [inheritance](/en-US/docs/Web/CSS/Inheritance) -- {{Glossary("Property/CSS", "CSS property")}} glossary term +- [CSS inheritance](/en-US/docs/Web/CSS/Inheritance) +- {{Glossary("Property/CSS", "CSS property")}} [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module: - [custom property (`--*`)](/en-US/docs/Web/CSS/--*) -- {{cssxref("var")}} +- {{cssxref("var")}} function -[CSS conditional rules](/en-US/docs/Web/CSS/CSS_conditional_rules) module +[CSS conditional rules](/en-US/docs/Web/CSS/CSS_conditional_rules) module: -- {{cssxref("@media")}} -- {{cssxref("@supports")}} +- {{cssxref("@media")}} at-rule +- {{cssxref("@supports")}} at-rule -[CSS Object Model (CSSOM)](/en-US/docs/Web/API/CSS_Object_Model) module +[CSS Object Model (CSSOM)](/en-US/docs/Web/API/CSS_Object_Model) API: -- {{domxref("CSSValue.cssText", "cssText")}} -- {{domxref("CSSStyleSheet.insertRule()", "insertRule(rule)")}} -- {{domxref("CSSStyleSheet.replace()", "replace(text)")}} +- {{domxref("CSSValue.cssText", "cssText")}} property +- {{domxref("CSSStyleSheet.insertRule()", "insertRule(rule)")}} method +- {{domxref("CSSStyleSheet.replace()", "replace(text)")}} method -[WHATWG](/en-US/docs/Glossary/WHATWG) specification +[WHATWG](/en-US/docs/Glossary/WHATWG) specification: -- {{HTMLElement("style")}} -- {{HTMLElement("link")}} +- {{HTMLElement("style")}} element +- {{HTMLElement("link")}} element - [`class`](/en-US/docs/Web/HTML/Global_attributes/class) attribute - [`rel`](/en-US/docs/Web/HTML/Attributes/rel#stylesheet) attribute From 24772a49d64d3f7254f21e33643b4b8f990d4dd1 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Fri, 8 Dec 2023 19:38:29 -0800 Subject: [PATCH 16/43] change h2 to h3 --- files/en-us/web/css/css_syntax/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md index c1440e4c3daa4a4..b4e04007d55bc2c 100644 --- a/files/en-us/web/css/css_syntax/index.md +++ b/files/en-us/web/css/css_syntax/index.md @@ -26,7 +26,7 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru - [invalid](/en-US/docs/Web/CSS/CSS_syntax/error_handling) - [style rule](/en-US/docs/Web/API/CSSStyleRule) -## Glossary terms +### Glossary terms - {{glossary("CSS_Descriptor", "CSS descriptor")}} - {{glossary("parse")}} From 4d5c5821eb72cf4be4727336706edaeba8c2dca5 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 13 Dec 2023 12:09:06 -0800 Subject: [PATCH 17/43] Apply suggestions from code review Co-authored-by: Dipika Bhattacharya --- files/en-us/web/css/@charset/index.md | 2 +- .../css/css_syntax/error_handling/index.md | 58 +++++++++---------- files/en-us/web/css/custom-ident/index.md | 2 +- 3 files changed, 31 insertions(+), 31 deletions(-) diff --git a/files/en-us/web/css/@charset/index.md b/files/en-us/web/css/@charset/index.md index e41f817b1f0e230..306e2b55999cb77 100644 --- a/files/en-us/web/css/@charset/index.md +++ b/files/en-us/web/css/@charset/index.md @@ -7,7 +7,7 @@ browser-compat: css.at-rules.charset {{CSSRef}} -The **`@charset`** [CSS](/en-US/docs/Web/CSS) rule specifies the character encoding used in the style sheet. Although the first character is the `@` symbol, it is not an [at-rule](/en-US/docs/Web/CSS/At-rule). The [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module deprecates this rule, defining it as an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked, but it is [fully supported in all browsers](#browser-compatibility). +The **`@charset`** [CSS](/en-US/docs/Web/CSS) rule specifies the character encoding used in the style sheet. Although the first character in `@charset` is the `@` symbol, it is not an [at-rule](/en-US/docs/Web/CSS/At-rule). The [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module deprecates this rule, defining it as an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked, but it is [fully supported in all browsers](#browser-compatibility). The `@charset` rule must be the first element in the style sheet and not be preceded by any character; as it is not a [nested statement](/en-US/docs/Web/CSS/Syntax#nested_statements), it cannot be used inside [conditional group at-rules](/en-US/docs/Web/CSS/At-rule#conditional_group_rules). If several `@charset` at-rules are defined, only the first one is used, and it cannot be used inside a `style` attribute on an HTML element or inside the {{ HTMLElement("style") }} element where the character set of the HTML page is relevant. diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index cd0dfd6dedd6261..1d15e329a4b8ec0 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -1,56 +1,56 @@ --- -title: CSS syntax error handling +title: CSS syntax errors slug: Web/CSS/CSS_syntax/error_handling page-type: guide --- {{CSSRef}} -When an error is made in CSS, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser will gracefully recover, skipping over the invalid content. While the user agent won't alert you to CSS errors, the user agent won't fail either. This is a feature of CSS, not a bug. +When an error is made in CSS, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser will gracefully recover, skipping the invalid content. While the user agent won't alert you to CSS errors, the user agent won't fail either. This is a feature of CSS, not a bug. -In CSS, when an error is made, the user-agent's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to parsing as normal. This error recovery is done because, as new features are added to CSS, a browser may not recognize new features and will simply discard the line with the content with what it may currently view as an error. This enables adding new features to CSS without worrying that anything, other than the new feature, is broken in older browsers. It also enables including both old and new syntax, in that order, so the old syntax is rendered until the new syntax becomes parsed as valid. Because user agents ignore CSS errors, the valid fallback CSS doesn't get overwritten by perceived as invalid new CSS. +When an error is made in CSS, the user-agent's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to parsing as normal. As new features are added to CSS, a browser may not recognize these new features. The recovery from errors allows a browser to discard the line containing the unrecognized content. This CSS feature allows for adding new features to CSS without worrying that anything, other than the new feature, is broken in older browsers. It also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because user agents ignore CSS errors, the valid fallback CSS doesn't get overwritten by perceived as invalid new CSS. -The type and amount of CSS that gets ignored depends on the type of error. For example, +The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some of common error situations are listed below: - For [errors in at-rules](#at-rule-errors), whether a single line or the entire at-rule fails depends on the at-rule and the type of error. -- If the error is an [invalid selector](#errors-in-selector-lists), the entire declaration block is ignored. -- If a semi-colon is omitted between property declarations, the [missing semi-colon](#errors-within-css-declaration-blocks) causes an invalid value, so the declaration is ignored. -- If the [error is a property name or value](#errors-within-css-declaration-blocks), such as an unrecognized property name or invalid data type, just that property/value declaration is ignored. -- If the issue is a [missing end-bracket](#auto-closed-endings), what gets ignored, if anything, depends on whether the user-agent can parse the error as nested CSS. +- If the [error is an invalid selector](#errors-in-selector-lists), the entire declaration block is ignored. +- An [error due to a missing semi-colon](#errors-within-css-declaration-blocks) between property declarations causes an invalid value, in which case, the property-value declaration is ignored. +- If the [error is a property name or value](#errors-within-css-declaration-blocks), such as an unrecognized property name or invalid data type, the property-value declaration is ignored. +- If the [error is due to a missing end-bracket](#auto-closed-endings), the extent of what is ignored depends on the browser's ability to parse the error as nested CSS. -After each declaration, style rule, at-rule, etc. is parsed, the user agent checks the parsed content against its expected [grammar](#grammar-check) for that construct. If it does not match the expected grammar for that construct, it is invalid and is ignored. +After parsing each declaration, style rule, at-rule, and so on, the browser checks the parsed content against its expected [grammar](#grammar-check) for that construct. If the content does not match the expected grammar for that construct, the browser considers it invalid and ignores it. ## CSS parser errors ### At-rule errors -The `@`, known in the CSS specifications as an ``, indicates the beginning of an {{cssxref("at-rule")}}. CSS includes at-rules that contain just a prelude, like {{cssxref("@import")}} or some {{cssxref("@layer")}} declarations, and at-rule blocks that contain a body of declarations, like {{cssxref("@keyframes")}}, {{cssxref("@font-face")}}, and `@layer` declarations that include styles blocks. These at-rule blocks are generally multi-statement and referred to as multi-line, even though they can be declared with no line breaks. +The `@` symbol, known in the CSS specifications as an ``, indicates the beginning of an {{cssxref("at-rule")}}. Some at-rules such as {{cssxref("@import")}} and some {{cssxref("@layer")}} declarations contain just a prelude and and other at-rule blocks contain a body of declarations, as in {{cssxref("@keyframes")}}, {{cssxref("@font-face")}}, and `@layer` declarations, which include styles blocks. These at-rule blocks are generally multi-statement and referred to as multi-line, even though they can be declared with no line breaks. -Once an at-rule is started with the `@`, nothing is invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or opening curly brace (`{`) is part of the at-rule's prelude. The semicolon ends the at-rule immediately for single-line at-rules. If there is an open curly brace, this informs the browser where the completed at-rule prelude ends and the at-rule's body starts. For these multi-line at-rules, the parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. The contents of the at-rule are then interpreted according to the grammar rules for that particular at-rule. +Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The semicolon ends the at-rule immediately for single-line at-rules. If there is an open curly brace, this informs the browser where the completed at-rule prelude ends and the at-rule's body starts. For these multi-line at-rules, the parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. The contents of the at-rule are then interpreted according to the grammar rules for that particular at-rule. -> **Note:** Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what will invalidate the entire at-rule, if anything. The expected grammar for each at-rule, and how errors are handled, are documented on each individual at-rule page. +> **Note:** Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what will invalidate the entire at-rule, if at all. The expected grammar for each at-rule and how errors are handled are documented on the respective at-rule page. -For example, if an `@import` occurs after any other CSS declarations, other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. A `@layer` statement, which can be declared either as a prelude or contain a body of declarations, will always create at least an anonymous layer. If there is a declaration body, the handling of any error depends on the error. The user-agent won't fail; rather, invalid CSS is ignored. If the error is a missing closing curly brace, you have a logic error not a CSS error. In the case of a missing closing brace in an `@layer`, the styles will be assumed to be in the cascade layer defined in the at-rule's prelude. This is a developer mistake, a logic error. The CSS is considered valid; nothing is invalid, so nothing is ignored by the parser. +For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. A `@layer` statement, which can be declared either as a prelude or can contain a body of declarations, will always create at least an anonymous layer. If there is a declaration body, the handling of any error depends on the error. The user-agent won't fail; rather, invalid CSS is ignored. If the error is a missing closing curly brace, it is considered a logic error not a CSS error. In the case of a missing closing brace in `@layer`, the styles are assumed to be in the cascade layer that is defined in the at-rule's prelude. This represents a developer mistake, a logic error. In this case, the CSS is considered valid; because there are no syntactic errors, the parser does not ignore any part. ### Errors in selector lists There are many ways you might make a mistake writing a selector, but only invalid selectors cause [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list) issues. -If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element that doesn't exist, it may be a logic error, but not an error the parser needs to handle. If, however, you have a typo in a pseudo-class or pseudo-element, that may create an invalid selector, which is an error the parser will notice. +If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element, respectively, that doesn't exist, it may be a logic error, but it's not an error the parser needs to handle. If, however, you have a typo in a pseudo-class or a pseudo-element, it might create an invalid selector, which is an error the parser will notice. -If a selector list contains any invalid selectors, it is an [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list) and the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-classes, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list) or if the unknown selectors is a [`-webkit-` prefixed pseudo-element](#webkit-exception), only the unknown selector is ignored as not matching anything. The selector list is not be invalidated.. +If a selector list contains any selectors that are in the [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list), then the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-class, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list) or if the unknown selector is a [`-webkit-` prefixed pseudo-element](#webkit-exception), only the unknown selector is ignored as not matching anything. The selector list is not invalidated. -If a selector list contains any invalid selectors outside of these exception, a single invalid or unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The user-agent will look for the closing curly brace and will continue parsing again from that point on. +If a selector list contains any invalid selectors outside of these exceptions, a single invalid or unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The user-agent will look for the closing curly brace and will continue parsing again from that point on. #### Webkit exception -Due to legacy issues with the overuse of browser prefixes in selectors (and [property names and values](#vendor-prefixes)), to prevent the invalidation of selector lists, browsers treat all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a `-webkit-` prefix, case-insensitive, and that don't end with `()`, as valid. +Due to legacy issues from the overuse of browser-specific prefixes in selectors and in [property names and values](#vendor-prefixes), browsers avoid the invalidation of selector lists by treating all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a case-insensitive `-webkit-` prefix and don't end with `()` as valid. -This means that `::-webkit-works-only-in-samsung` will not invalidate a selector list no matter the browser. In such cases, the pseudo-element may not be recognized or supported by the browser, but if a `-webkit-` prefixed pseudo-element will not cause the entire selector list and it's associated style block to be ignored. On the other hand, the unknown prefixed selector with a function notation `::-webkit-imaginary-function()` will invalidate the entire selector list and the browser will ignore the entire selector block. +This means that a pseudo-element like `::-webkit-works-only-in-samsung` will not invalidate a selector list, regardless of the browser. In such cases, the pseudo-element may not be recognized or supported by the browser, but it will not cause the entire selector list and it's associated style block to be ignored. On the other hand, the unknown prefixed selector with a function notation `::-webkit-imaginary-function()` will invalidate the entire selector list and the browser will ignore the entire selector block. ### Errors within CSS declaration blocks -When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parses, or interprets, a list of declarations, unknown syntax at any point causes the user-agent's parser to discard just that rule and continue parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. +When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parses or interprets a list of declarations, unknown syntax at any point causes the user-agent's parser to discard only that specific rule. It then continues parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. The parser seeks forward until it finds a semicolon (or the end of the block). It then starts fresh, trying to parse a declaration again. @@ -58,18 +58,18 @@ This example contains an error. The parser ignores the error (and the comments), ```css-nolint bad p { -/* invalid due to missing semi-colon */ +/* Invalid syntax due to missing semi-colon */ border-color: red background-color: green; -/* valid, though it is likely a mistake */ +/* Valid syntax but likely a logic error */ border-width: 100vh; } ``` -The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last declaration in the block. The property missing the semi-colon is ignored, as is the pair following it, as the browser only continues parsing after a semi-colon or closing bracket is encountered. In the above CSS, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. +The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last declaration in the block. The property missing the semi-colon is ignored, as is the property-value pair following it because the browser only continues parsing after a semi-colon or closing bracket is encountered. In the above CSS, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. -The parser ignores the property with a invalid value, and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is valid, it will be parsed and applied to the elements matching the selector. +The parser ignores the property with an invalid value, and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is syntactically valid, it will be parsed and applied to the elements matching the selector. #### Vendor prefixes @@ -78,14 +78,14 @@ Vendor-prefixed property names and property values, when not understood by a bro You may come across legacy CSS that looks like the following: ```css example-bad -/* prefixed values */ +/* Prefixed values */ .wrapper { display: -webkit-box; display: -webkit-flex; display: -ms-flexbox; display: flex; } -/* prefixed properties */ +/* Prefixed properties */ .rounded { -webkit-border-radius: 50%; -moz-border-radius: 50%; @@ -95,11 +95,11 @@ You may come across legacy CSS that looks like the following: } ``` -The valid CSS rules are the last ones in each declaration block above. The parser ignores the rules it doesn't understand as invalid. If the user agent does understand one of the prefixed rules, as all browsers understand `display: flex;` and `border-radius: 50%;`, the values in the last, valid declaration are used, not because they are the valid ones, but rather due to the [cascade](/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#source_order) [order of appearance](/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) rule. +In both the declaration blocks above, the last declaration is valid. The parser ignores the declarations it doesn't understand as invalid. If the user agent does understand one of the prefixed declarations, for example, all browsers understand `display: flex;` and `border-radius: 50%;`, the values in the last, valid declaration are used, not because they are the valid ones, but rather due to the [cascade](/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#source_order) [order of appearance](/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) rule. -> **Note:** Avoid including prefixed properties or property values. If you must, declare the prefixed values before the valid, non-prefixed standard compliant property and value. +> **Note:** Avoid including prefixed properties or property values. If you must, declare the prefixed values before the valid, non-prefixed standard property-value pairs. -### Auto-closed endings +### Errors with auto-closed endings If a stylesheet — be it an external style sheet, selector blocks within an HTML {{HTMLElement("style")}} element, or inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. @@ -107,7 +107,7 @@ If the content between the last semi-colon and the end of the stylesheet is vali > **Note:** Do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS you intended. -> **Note:** If a comment is with `/*` but not closed, any and all CSS encountered until the closing comment `*/` is found will be treated as a comment. Forgetting to close a comment may not make your CSS invalid, but it will make cause the CSS inside the comment to be ignored. +> **Note:** If a comment starts with `/*` but is not closed, all CSS code until the closing comment `*/` is encountered will be treated as part of the comment. While an unclosed comment does not invalidate your CSS, but it causes the CSS inside the comment to be ignored. ### Grammar check diff --git a/files/en-us/web/css/custom-ident/index.md b/files/en-us/web/css/custom-ident/index.md index 041fad7aa76cb43..22162a8f3a63350 100644 --- a/files/en-us/web/css/custom-ident/index.md +++ b/files/en-us/web/css/custom-ident/index.md @@ -32,7 +32,7 @@ Any Unicode code point can be included as part of a `` or quoted { In CSS, there are several ways to escape a character. Escape sequences start with a backslash (`\`), and continue with: -- One to six hex (`ABCDEF0123456789`) digits. The hex digits can optionally be followed white space. The hex escape sequence gets replaced by the Unicode code point whose value is given by those digits. The whitespace allows the sequences to be followed by actual hex digits (versus replaced ones). +- One to six hex (`ABCDEF0123456789`) digits. The hex digits can optionally be followed by white space. The hex escape sequence gets replaced by the Unicode code point whose value is given by those digits. The whitespace allows the sequences to be followed by actual hex digits (versus replaced ones). - Any Unicode code point that is not a hex digit or a newline character. Examples: From 71944f1da0d289fc812e9e7429743b251f95cf6a Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 13 Dec 2023 12:59:50 -0800 Subject: [PATCH 18/43] add guide to module page. --- files/en-us/web/css/css_syntax/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md index b4e04007d55bc2c..26cb3b664c1bd96 100644 --- a/files/en-us/web/css/css_syntax/index.md +++ b/files/en-us/web/css/css_syntax/index.md @@ -46,6 +46,10 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru - [CSS syntax error handling](/en-US/docs/Web/CSS/CSS_syntax/error_handling) - : Overview of how the user-agent handles invalid CSS + +- [Learn CSS first steps: CSS syntax](/en-US/docs/Learn/CSS/First_steps/What_is_CSS#css_syntax) + + - : Introductory guide to CSS, including an introcution to CSS syntax. ## Related concepts From e2878426117d5f14c7ad786b94f8be482af2184a Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 13 Dec 2023 13:27:32 -0800 Subject: [PATCH 19/43] change UA to browser --- files/en-us/web/css/css_syntax/error_handling/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 1d15e329a4b8ec0..71e894273209f42 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -6,9 +6,9 @@ page-type: guide {{CSSRef}} -When an error is made in CSS, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser will gracefully recover, skipping the invalid content. While the user agent won't alert you to CSS errors, the user agent won't fail either. This is a feature of CSS, not a bug. +When an error, such as an invalid value or a missing semicolon, exists in CSS, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser or other user-agent will gracefully recover, skipping the invalid content. Browser doesn't provide CSS-error-related alerts or otherwise indicate erros have occurred. This is a feature of CSS, not a bug. -When an error is made in CSS, the user-agent's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to parsing as normal. As new features are added to CSS, a browser may not recognize these new features. The recovery from errors allows a browser to discard the line containing the unrecognized content. This CSS feature allows for adding new features to CSS without worrying that anything, other than the new feature, is broken in older browsers. It also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because user agents ignore CSS errors, the valid fallback CSS doesn't get overwritten by perceived as invalid new CSS. +When an error is made in CSS, the browser's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to parsing as normal. As new features are added to CSS, a browser may not recognize these new features. The recovery from errors allows a browser to discard the line containing the unrecognized content. This CSS feature allows for adding new features to CSS without worrying that anything, other than the new feature, is broken in older browsers. It also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because user agents ignore CSS errors, the valid fallback CSS doesn't get overwritten by perceived as invalid new CSS. The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some of common error situations are listed below: @@ -30,7 +30,7 @@ Once an at-rule begins with the `@` symbol, nothing is considered invalid from t > **Note:** Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what will invalidate the entire at-rule, if at all. The expected grammar for each at-rule and how errors are handled are documented on the respective at-rule page. -For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. A `@layer` statement, which can be declared either as a prelude or can contain a body of declarations, will always create at least an anonymous layer. If there is a declaration body, the handling of any error depends on the error. The user-agent won't fail; rather, invalid CSS is ignored. If the error is a missing closing curly brace, it is considered a logic error not a CSS error. In the case of a missing closing brace in `@layer`, the styles are assumed to be in the cascade layer that is defined in the at-rule's prelude. This represents a developer mistake, a logic error. In this case, the CSS is considered valid; because there are no syntactic errors, the parser does not ignore any part. +For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. A `@layer` statement, which can be declared either as a prelude or can contain a body of declarations, will always create at least an anonymous layer. If there is a declaration body, the handling of any error depends on the error. The browser won't fail; rather, invalid CSS is ignored. If the error is a missing closing curly brace, it is considered a logic error not a CSS error. In the case of a missing closing brace in `@layer`, the styles are assumed to be in the cascade layer that is defined in the at-rule's prelude. This represents a developer mistake, a logic error. In this case, the CSS is considered valid; because there are no syntactic errors, the parser does not ignore any part. ### Errors in selector lists @@ -40,7 +40,7 @@ If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selector If a selector list contains any selectors that are in the [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list), then the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-class, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list) or if the unknown selector is a [`-webkit-` prefixed pseudo-element](#webkit-exception), only the unknown selector is ignored as not matching anything. The selector list is not invalidated. -If a selector list contains any invalid selectors outside of these exceptions, a single invalid or unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The user-agent will look for the closing curly brace and will continue parsing again from that point on. +If a selector list contains any invalid selectors outside of these exceptions, a single invalid or unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The browser will look for the closing curly brace and will continue parsing again from that point on. #### Webkit exception @@ -50,7 +50,7 @@ This means that a pseudo-element like `::-webkit-works-only-in-samsung` will not ### Errors within CSS declaration blocks -When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parses or interprets a list of declarations, unknown syntax at any point causes the user-agent's parser to discard only that specific rule. It then continues parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. +When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parses or interprets a list of declarations, unknown syntax at any point causes the browser's parser to discard only that specific rule. It then continues parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. The parser seeks forward until it finds a semicolon (or the end of the block). It then starts fresh, trying to parse a declaration again. From 50c42cea4d5b64d71ce8d31c41b9f19576fd97e6 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 13 Dec 2023 13:36:58 -0800 Subject: [PATCH 20/43] address https://github.com/mdn/content/pull/30793#discussion_r1421245493 --- files/en-us/web/css/css_syntax/error_handling/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 71e894273209f42..965507a09188cf9 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -6,9 +6,9 @@ page-type: guide {{CSSRef}} -When an error, such as an invalid value or a missing semicolon, exists in CSS, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser or other user-agent will gracefully recover, skipping the invalid content. Browser doesn't provide CSS-error-related alerts or otherwise indicate erros have occurred. This is a feature of CSS, not a bug. +When an error, such as an invalid value or a missing semicolon, exists in CSS, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser or other user-agent will gracefully recover, skipping the invalid content. Browsers don't provide CSS-related alerts or otherwise indicate errors have occurred in styles. This is a feature of CSS, not a bug. -When an error is made in CSS, the browser's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to parsing as normal. As new features are added to CSS, a browser may not recognize these new features. The recovery from errors allows a browser to discard the line containing the unrecognized content. This CSS feature allows for adding new features to CSS without worrying that anything, other than the new feature, is broken in older browsers. It also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because user agents ignore CSS errors, the valid fallback CSS doesn't get overwritten by perceived as invalid new CSS. +When a CSS error is encountered, the browser's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to parsing as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. This CSS feature allows for the addition of new CSS features without worrying that anything, other than the new feature, will be broken in older browsers. It also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because browsers ignore CSS errors, the valid fallbacks don't get overwritten by new CSS that is perceived as invalid. The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some of common error situations are listed below: From 1ea3167db540752e67b3c5c31bfe057440f4d0ff Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Wed, 13 Dec 2023 13:39:59 -0800 Subject: [PATCH 21/43] hyphens to underscores --- .../en-us/web/css/css_syntax/error_handling/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 965507a09188cf9..2db0604a483c6fe 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -12,13 +12,13 @@ When a CSS error is encountered, the browser's parser ignores the lines containi The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some of common error situations are listed below: -- For [errors in at-rules](#at-rule-errors), whether a single line or the entire at-rule fails depends on the at-rule and the type of error. -- If the [error is an invalid selector](#errors-in-selector-lists), the entire declaration block is ignored. -- An [error due to a missing semi-colon](#errors-within-css-declaration-blocks) between property declarations causes an invalid value, in which case, the property-value declaration is ignored. -- If the [error is a property name or value](#errors-within-css-declaration-blocks), such as an unrecognized property name or invalid data type, the property-value declaration is ignored. -- If the [error is due to a missing end-bracket](#auto-closed-endings), the extent of what is ignored depends on the browser's ability to parse the error as nested CSS. +- For [errors in at-rules](#at-rule_errors), whether a single line or the entire at-rule is ignored (fails) depends on the at-rule and the type of error. +- If the [error is an invalid selector](#errors_in_selector_lists), the entire declaration block is ignored. +- An [error due to a missing semi-colon](#errors_within_css_declaration_blocks) between property declarations causes an invalid value, in which case, the property-value declaration is ignored. +- If the [error is a property name or value](#errors_within_css_declaration_blocks), such as an unrecognized property name or invalid data type, the property-value declaration is ignored. +- If the [error is due to a missing end-bracket](#auto-closed_endings), the extent of what is ignored depends on the browser's ability to parse the error as nested CSS. -After parsing each declaration, style rule, at-rule, and so on, the browser checks the parsed content against its expected [grammar](#grammar-check) for that construct. If the content does not match the expected grammar for that construct, the browser considers it invalid and ignores it. +After parsing each declaration, style rule, at-rule, and so on, the browser checks the parsed content against its expected [grammar](#grammar_check) for that construct. If the content does not match the expected grammar for that construct, the browser considers it invalid and ignores it. ## CSS parser errors From e0f68c2813b63bb6e4bfe9c67c855a14fd43d7a8 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Thu, 14 Dec 2023 01:07:39 -0800 Subject: [PATCH 22/43] rewrote the at-rule section --- .../css/css_syntax/error_handling/index.md | 26 ++++++++++++------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 2db0604a483c6fe..bce78c797e396b3 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -6,9 +6,11 @@ page-type: guide {{CSSRef}} -When an error, such as an invalid value or a missing semicolon, exists in CSS, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser or other user-agent will gracefully recover, skipping the invalid content. Browsers don't provide CSS-related alerts or otherwise indicate errors have occurred in styles. This is a feature of CSS, not a bug. +When an error exists in CSS, such as an invalid value or a missing semicolon, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser (or other user-agent) will gracefully recover, skipping the invalid content. Browsers don't provide CSS-related alerts or otherwise indicate errors have occurred in styles. This is a feature of CSS, not a bug. -When a CSS error is encountered, the browser's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to parsing as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. This CSS feature allows for the addition of new CSS features without worrying that anything, other than the new feature, will be broken in older browsers. It also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because browsers ignore CSS errors, the valid fallbacks don't get overwritten by new CSS that is perceived as invalid. +When a CSS error is encountered, the browser's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. + +The fact that browsers ignore invalid code enables using new CSS features without worrying about anything being broken in older browsers. This feature also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because browsers ignore invalid CSS, the valid fallbacks don't get overwritten by new CSS that is perceived as invalid. The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some of common error situations are listed below: @@ -24,13 +26,19 @@ After parsing each declaration, style rule, at-rule, and so on, the browser chec ### At-rule errors -The `@` symbol, known in the CSS specifications as an ``, indicates the beginning of an {{cssxref("at-rule")}}. Some at-rules such as {{cssxref("@import")}} and some {{cssxref("@layer")}} declarations contain just a prelude and and other at-rule blocks contain a body of declarations, as in {{cssxref("@keyframes")}}, {{cssxref("@font-face")}}, and `@layer` declarations, which include styles blocks. These at-rule blocks are generally multi-statement and referred to as multi-line, even though they can be declared with no line breaks. +The `@` symbol, known in the CSS specifications as an ``, indicates the beginning of an {{cssxref("at-rule")}}. Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The contents of each at-rule is interpreted according to the grammar rules for that particular at-rule. + +Statement at-rules, such as {{cssxref("@import")}} and {{cssxref("@namespace")}} declarations, contain just a prelude. The semicolon ends the at-rule immediately for single-line at-rules. If the contents of the prelude are invalid according to the grammar for that at-rule, the at-rule is ignored, with the browser continuing to parse CSS after it encounters the next semi-colon. For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. + +If the parser encounter a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rule. Block at-rules, like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the completed at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. + +Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what, if anything, will invalidate the entire at-rule. The expected grammar for each at-rule and how errors are handled are documented on the respective at-rule page. The handling of invalid content depends on the error. -Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The semicolon ends the at-rule immediately for single-line at-rules. If there is an open curly brace, this informs the browser where the completed at-rule prelude ends and the at-rule's body starts. For these multi-line at-rules, the parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. The contents of the at-rule are then interpreted according to the grammar rules for that particular at-rule. +For the `@font-face` at-rule, including an unrelated descriptor, a valid font-face descriptor with an invalid value, or a property style declaration within an `@font-face` will not invalidate the font declaration. Only the invalid CSS is ignored. -> **Note:** Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what will invalidate the entire at-rule, if at all. The expected grammar for each at-rule and how errors are handled are documented on the respective at-rule page. +The grammar of the `@font-face` at-rule is very different from the `@keyframe`, with the type of error impacting what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated in keyframe rules are ignored, but normal, supported properties will still be animated. Including a keyframe selector percentage value less than `0%`, greater than `100%`, or omitting the `%`, invalidates the keyframe selector list. The style block is ignored but does not cause the entire at-rule to be invalid. Including styles between two keyframe selector blocks within a `@keyframe`, however, does invalidate the entire `@keyframe` at-rule. -For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. A `@layer` statement, which can be declared either as a prelude or can contain a body of declarations, will always create at least an anonymous layer. If there is a declaration body, the handling of any error depends on the error. The browser won't fail; rather, invalid CSS is ignored. If the error is a missing closing curly brace, it is considered a logic error not a CSS error. In the case of a missing closing brace in `@layer`, the styles are assumed to be in the cascade layer that is defined in the at-rule's prelude. This represents a developer mistake, a logic error. In this case, the CSS is considered valid; because there are no syntactic errors, the parser does not ignore any part. +Some at-rules are almost always. The statement {{cssxref("@layer")}} contains just the prelude, ending with a semi-colon. Alternatively, this at-rule can also have layer styles nested between curly braces following the prelude. If the error is a missing closing curly brace, it is considered a logic error not a CSS error. In the case of a missing closing brace in `@layer`, the styles are assumed to be in the cascade layer that is defined in the at-rule's prelude. The CSS is considered valid; because there are no syntactic errors, the parser does not ignore any part. The `@layer` statement, whether it contains just a prelude statement ending with a semi-color or if it contains a body of declarations, as long as the layer name is not a [global CSS value](), the at-rule always creates at least one layer, though the layer may be an anonymous layer containing no styles. ### Errors in selector lists @@ -69,7 +77,7 @@ p { The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last declaration in the block. The property missing the semi-colon is ignored, as is the property-value pair following it because the browser only continues parsing after a semi-colon or closing bracket is encountered. In the above CSS, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. -The parser ignores the property with an invalid value, and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is syntactically valid, it will be parsed and applied to the elements matching the selector. +The parser ignores the property with an invalid value and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is syntactically valid, it will be parsed and applied to the elements matching the selector. #### Vendor prefixes @@ -103,7 +111,7 @@ In both the declaration blocks above, the last declaration is valid. The parser If a stylesheet — be it an external style sheet, selector blocks within an HTML {{HTMLElement("style")}} element, or inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. -If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. Failing to properly close CSS statements doesn't necessarily make the statements invalid. +If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. Failing to close CSS statements properly doesn't necessarily make the statements invalid. > **Note:** Do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS you intended. @@ -111,7 +119,7 @@ If the content between the last semi-colon and the end of the stylesheet is vali ### Grammar check -After each declaration, style rule, at-rule, etc. is parsed, the user agent checks to make sure the grammar is the expected grammar for that declaration. For example, if a property value is of the wrong data type or if a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid, and gets ignored. +After each declaration, style rule, at-rule, etc. is parsed, the user agent checks to ensure the grammar is the expected grammar for that declaration. For example, if a property value is of the wrong data type or if a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid, and gets ignored. ## See also From ab85e39246d3b9d17dccb5ca48c61e807cccb444 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Thu, 14 Dec 2023 16:38:33 -0800 Subject: [PATCH 23/43] rewrite grammar section --- .../css/css_syntax/error_handling/index.md | 49 ++++++++++++++++--- 1 file changed, 41 insertions(+), 8 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index bce78c797e396b3..e4f8a2c9e5c5b0c 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -8,7 +8,11 @@ page-type: guide When an error exists in CSS, such as an invalid value or a missing semicolon, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser (or other user-agent) will gracefully recover, skipping the invalid content. Browsers don't provide CSS-related alerts or otherwise indicate errors have occurred in styles. This is a feature of CSS, not a bug. -When a CSS error is encountered, the browser's parser ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. +This guide discusses how CSS {{glossary("parser", "parsers")}} discard invalid CSS. + +## CSS parser errors + +When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. The fact that browsers ignore invalid code enables using new CSS features without worrying about anything being broken in older browsers. This feature also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because browsers ignore invalid CSS, the valid fallbacks don't get overwritten by new CSS that is perceived as invalid. @@ -22,8 +26,6 @@ The type and amount of CSS that a browser ignores due to an error depends on the After parsing each declaration, style rule, at-rule, and so on, the browser checks the parsed content against its expected [grammar](#grammar_check) for that construct. If the content does not match the expected grammar for that construct, the browser considers it invalid and ignores it. -## CSS parser errors - ### At-rule errors The `@` symbol, known in the CSS specifications as an ``, indicates the beginning of an {{cssxref("at-rule")}}. Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The contents of each at-rule is interpreted according to the grammar rules for that particular at-rule. @@ -36,7 +38,7 @@ Different at-rules have different grammar rules, different (or no) descriptors, For the `@font-face` at-rule, including an unrelated descriptor, a valid font-face descriptor with an invalid value, or a property style declaration within an `@font-face` will not invalidate the font declaration. Only the invalid CSS is ignored. -The grammar of the `@font-face` at-rule is very different from the `@keyframe`, with the type of error impacting what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated in keyframe rules are ignored, but normal, supported properties will still be animated. Including a keyframe selector percentage value less than `0%`, greater than `100%`, or omitting the `%`, invalidates the keyframe selector list. The style block is ignored but does not cause the entire at-rule to be invalid. Including styles between two keyframe selector blocks within a `@keyframe`, however, does invalidate the entire `@keyframe` at-rule. +The grammar of the `@font-face` at rule is very different from the `@keyframe`, with the type of error impacting what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated in keyframe rules are ignored, but normal, supported properties will still be animated. Including a keyframe selector percentage value less than `0%`, greater than `100%`, or with the `%` sign omitted invalidates the keyframe selector list and therefore the style block is ignored, but an invalid keyframe selector doesn't not invalidate the entire `@keyframe`. Including styles between two keyframe selector block within a `@keyframe` invalidates the at-rule. Some at-rules are almost always. The statement {{cssxref("@layer")}} contains just the prelude, ending with a semi-colon. Alternatively, this at-rule can also have layer styles nested between curly braces following the prelude. If the error is a missing closing curly brace, it is considered a logic error not a CSS error. In the case of a missing closing brace in `@layer`, the styles are assumed to be in the cascade layer that is defined in the at-rule's prelude. The CSS is considered valid; because there are no syntactic errors, the parser does not ignore any part. The `@layer` statement, whether it contains just a prelude statement ending with a semi-color or if it contains a body of declarations, as long as the layer name is not a [global CSS value](), the at-rule always creates at least one layer, though the layer may be an anonymous layer containing no styles. @@ -77,7 +79,7 @@ p { The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last declaration in the block. The property missing the semi-colon is ignored, as is the property-value pair following it because the browser only continues parsing after a semi-colon or closing bracket is encountered. In the above CSS, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. -The parser ignores the property with an invalid value and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is syntactically valid, it will be parsed and applied to the elements matching the selector. +The parser ignores the property with an invalid value, and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is syntactically valid, it will be parsed and applied to the elements matching the selector. #### Vendor prefixes @@ -111,15 +113,46 @@ In both the declaration blocks above, the last declaration is valid. The parser If a stylesheet — be it an external style sheet, selector blocks within an HTML {{HTMLElement("style")}} element, or inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. -If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. Failing to close CSS statements properly doesn't necessarily make the statements invalid. +If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. Failing to properly close CSS statements doesn't necessarily make the statements invalid. > **Note:** Do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS you intended. > **Note:** If a comment starts with `/*` but is not closed, all CSS code until the closing comment `*/` is encountered will be treated as part of the comment. While an unclosed comment does not invalidate your CSS, but it causes the CSS inside the comment to be ignored. -### Grammar check +## Grammar check + +After each declaration, style rule, at-rule, etc. is parsed, the user agent checks to make sure the grammar is the expected grammar for that declaration. For example, if a property value is of the wrong data type or if a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid, and gets ignored. + +### Invalid custom properties + +Each CSS property accepts specific data types. For example, the {{cssxref("background-color")}} property accepts either a valid {{cssxref("<color>")}} or a CSS global keyword. When the value assigned to a property is of the wrong type, such as `background-color: 45deg`, the declaration is invalid and ignored. + +Custom properties are generally considered valid when declared, but may create invalid CSS when accessed. The browser parses each custom property when encountered without regard to where the property is consumed. A custom property may be valid when declared while creating an invalid value when passed as a parameter for the {{cssxref("var()")}} function for the grammar of where the `var()` function is found. + +While invalid CSS is discarded with the property value falling back to the last valid value, an invalid computed custom property value is slightly different. If the custom property declaration was valid and the grammar of the property using that value is valid, the declaration is valid at computed time. The `var()` value substitution can still be invalid. -After each declaration, style rule, at-rule, etc. is parsed, the user agent checks to ensure the grammar is the expected grammar for that declaration. For example, if a property value is of the wrong data type or if a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid, and gets ignored. +When a `var()` substitution is invalid, then the [initial](/en-US/docs/Web/CSS/initial_value) or [inherited](/en-US/docs/Web/CSS/Inheritance) value of the property is used; the declaration is not ignored. As the declaration was valid at compute time, the declaration is valid. This means the declaration is not ignored and the property does not remain the value of the previous valid value. Rather, the property is set to a new value, but possibly not the expected one. + +```css example-bad +:root { + --theme-color: 45deg; +} +body { + background-color: var(--theme-color); +} +``` + +In the above code, the custom property declaration is valid. The `background-color` declaration is also valid at compute time. However, when the browser substitutes the custom property in `var(--theme-color)` with `45deg`, the grammar is invalid. An {{cssxref("angle")}} is not a valid value `background-color`. In this case, the declaration is not ignored as invalid. Rather, when a custom property is of the wrong data-type, if the property is inheritable, the value is inherited from it's parent. If the property is not inheritable, the default initial value is used. In this case, the default background color is `transparent`. + +To better control the way custom properties fall back, use the {{cssxref("@property")}} at-rule to define the initial value of the property: + +```css example-good +@property --theme-color { + syntax: ""; + inherits: false; + initial-value: rebeccapurple; +} +``` ## See also From 53a33f3d84524e36f2bc4d6efb55e64298cb8442 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Thu, 14 Dec 2023 19:41:45 -0500 Subject: [PATCH 24/43] fixing linter suggestions Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/css/css_syntax/error_handling/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index e4f8a2c9e5c5b0c..0e6c47f28c0871c 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -12,7 +12,7 @@ This guide discusses how CSS {{glossary("parser", "parsers")}} discard invalid C ## CSS parser errors -When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. +When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. The fact that browsers ignore invalid code enables using new CSS features without worrying about anything being broken in older browsers. This feature also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because browsers ignore invalid CSS, the valid fallbacks don't get overwritten by new CSS that is perceived as invalid. @@ -32,11 +32,11 @@ The `@` symbol, known in the CSS specifications as an ``, indi Statement at-rules, such as {{cssxref("@import")}} and {{cssxref("@namespace")}} declarations, contain just a prelude. The semicolon ends the at-rule immediately for single-line at-rules. If the contents of the prelude are invalid according to the grammar for that at-rule, the at-rule is ignored, with the browser continuing to parse CSS after it encounters the next semi-colon. For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. -If the parser encounter a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rule. Block at-rules, like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the completed at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. +If the parser encounter a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rule. Block at-rules, like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the completed at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what, if anything, will invalidate the entire at-rule. The expected grammar for each at-rule and how errors are handled are documented on the respective at-rule page. The handling of invalid content depends on the error. -For the `@font-face` at-rule, including an unrelated descriptor, a valid font-face descriptor with an invalid value, or a property style declaration within an `@font-face` will not invalidate the font declaration. Only the invalid CSS is ignored. +For the `@font-face` at-rule, including an unrelated descriptor, a valid font-face descriptor with an invalid value, or a property style declaration within an `@font-face` will not invalidate the font declaration. Only the invalid CSS is ignored. The grammar of the `@font-face` at rule is very different from the `@keyframe`, with the type of error impacting what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated in keyframe rules are ignored, but normal, supported properties will still be animated. Including a keyframe selector percentage value less than `0%`, greater than `100%`, or with the `%` sign omitted invalidates the keyframe selector list and therefore the style block is ignored, but an invalid keyframe selector doesn't not invalidate the entire `@keyframe`. Including styles between two keyframe selector block within a `@keyframe` invalidates the at-rule. From debf7a9ec60272ddef02dcf26d375bb769b6f820 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Thu, 14 Dec 2023 16:57:39 -0800 Subject: [PATCH 25/43] final tweaks --- .../css/css_syntax/error_handling/index.md | 35 +++++++++++++++---- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 0e6c47f28c0871c..c86ef9039da3134 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -12,7 +12,7 @@ This guide discusses how CSS {{glossary("parser", "parsers")}} discard invalid C ## CSS parser errors -When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. +When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. The fact that browsers ignore invalid code enables using new CSS features without worrying about anything being broken in older browsers. This feature also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because browsers ignore invalid CSS, the valid fallbacks don't get overwritten by new CSS that is perceived as invalid. @@ -44,7 +44,7 @@ Some at-rules are almost always. The statement {{cssxref("@layer")}} contains ju ### Errors in selector lists -There are many ways you might make a mistake writing a selector, but only invalid selectors cause [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list) issues. +There are many ways you might make a mistake writing a selector, but only invalid selectors cause a selector list to be invalid (See [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list) issues). If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element, respectively, that doesn't exist, it may be a logic error, but it's not an error the parser needs to handle. If, however, you have a typo in a pseudo-class or a pseudo-element, it might create an invalid selector, which is an error the parser will notice. @@ -62,8 +62,6 @@ This means that a pseudo-element like `::-webkit-works-only-in-samsung` will not When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parses or interprets a list of declarations, unknown syntax at any point causes the browser's parser to discard only that specific rule. It then continues parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. -The parser seeks forward until it finds a semicolon (or the end of the block). It then starts fresh, trying to parse a declaration again. - This example contains an error. The parser ignores the error (and the comments), seeking forward until it encounters a semi-colon, then restarts parsing: ```css-nolint bad @@ -113,11 +111,34 @@ In both the declaration blocks above, the last declaration is valid. The parser If a stylesheet — be it an external style sheet, selector blocks within an HTML {{HTMLElement("style")}} element, or inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. -If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. Failing to properly close CSS statements doesn't necessarily make the statements invalid. +If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. For example, if you fail to close out an @keyframe declaration before closing your {{htmlelement("style")}}, the animation is still valid. + +```html-nolint example-bad + +``` + +The `move` animation is valid. Failing to properly close CSS statements doesn't necessarily make the statements invalid. That said, do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS you intended. -> **Note:** Do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS you intended. +### Unclosed comments + +Unclosed comments are logic errors, not syntax errors. If a comment starts with `/*` but is not closed, all CSS code until the closing comment `*/` is encountered will be treated as part of the comment. While an unclosed comment does not invalidate your CSS, it causes the CSS inside the comment to be ignored. + +```html example-bad + +

This html is ignored

+``` -> **Note:** If a comment starts with `/*` but is not closed, all CSS code until the closing comment `*/` is encountered will be treated as part of the comment. While an unclosed comment does not invalidate your CSS, but it causes the CSS inside the comment to be ignored. +In this example, the CSS comment was never closed so the closing `` tag was never parsed, and the subsquent HTML just became part of the CSS comment. ## Grammar check From a1c3201c646e2e57187f550c8273287b6575a366 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Thu, 14 Dec 2023 16:59:38 -0800 Subject: [PATCH 26/43] Update files/en-us/web/css/css_syntax/error_handling/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/css/css_syntax/error_handling/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index c86ef9039da3134..f49e9c202c9612a 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -129,11 +129,11 @@ Unclosed comments are logic errors, not syntax errors. If a comment starts with ```html example-bad

This html is ignored

``` From 496af3c53f914526640b23fe3214f490e390bbe7 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Thu, 14 Dec 2023 16:59:50 -0800 Subject: [PATCH 27/43] Update files/en-us/web/css/css_syntax/error_handling/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/css/css_syntax/error_handling/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index f49e9c202c9612a..5d1c16aa0792153 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -111,7 +111,7 @@ In both the declaration blocks above, the last declaration is valid. The parser If a stylesheet — be it an external style sheet, selector blocks within an HTML {{HTMLElement("style")}} element, or inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, etc. is still open, the parser will automatically close everything that was left unclosed. -If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. For example, if you fail to close out an @keyframe declaration before closing your {{htmlelement("style")}}, the animation is still valid. +If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. For example, if you fail to close out an @keyframe declaration before closing your {{htmlelement("style")}}, the animation is still valid. ```html-nolint example-bad -

This html is ignored

+

Parsed as HTML.

``` -In this example, the CSS comment was never closed so the closing `` tag was never parsed, and the subsquent HTML just became part of the CSS comment. +In this example, the two CSS comments are not closed, but the closing `` tag closes the first comment and the quote at the end of the `style` attribute closes the second comment. ## Grammar check From 3d99029caf8787418098682384b37f5edb997609 Mon Sep 17 00:00:00 2001 From: estelle Date: Fri, 15 Dec 2023 00:16:44 -0800 Subject: [PATCH 30/43] borked so fixed --- .../css/css_syntax/error_handling/index.md | 68 ++++++++++--------- 1 file changed, 37 insertions(+), 31 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index d4672578072209b..1fd94345b6b0109 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -6,17 +6,17 @@ page-type: guide {{CSSRef}} -When an error exists in CSS, such as an invalid value or a missing semicolon, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser (or other user-agent) will gracefully recover, skipping the invalid content. Browsers don't provide CSS-related alerts or otherwise indicate errors have occurred in styles. This is a feature of CSS, not a bug. +When an error exists in CSS, such as an invalid value or a missing semicolon, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser (or other user-agent) will gracefully recover. Browsers don't provide CSS-related alerts or otherwise indicate errors have occurred in styles. They just discard invalid content and parse subsequent valid styles. This is a feature of CSS, not a bug. This guide discusses how CSS {{glossary("parser", "parsers")}} discard invalid CSS. ## CSS parser errors -When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. As new features are added to CSS, a browser may not recognize these new features. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. +When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. -The fact that browsers ignore invalid code enables using new CSS features without worrying about anything being broken in older browsers. This feature also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because browsers ignore invalid CSS, the valid fallbacks don't get overwritten by new CSS that is perceived as invalid. +The fact that browsers ignore invalid code enables the use of new CSS features without worrying about anything being broken in older browsers. A browser may not recognize a new feature, but that is okay. The discarding of invalid content without throwing an error also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because browsers ignore invalid CSS, the valid fallbacks don't get overwritten by the new CSS that follows it that is perceived as invalid. -The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some of common error situations are listed below: +The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some common error situations are listed below: - For [errors in at-rules](#at-rule_errors), whether a single line or the entire at-rule is ignored (fails) depends on the at-rule and the type of error. - If the [error is an invalid selector](#errors_in_selector_lists), the entire declaration block is ignored. @@ -28,35 +28,40 @@ After parsing each declaration, style rule, at-rule, and so on, the browser chec ### At-rule errors -The `@` symbol, known in the CSS specifications as an ``, indicates the beginning of an {{cssxref("at-rule")}}. Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The contents of each at-rule is interpreted according to the grammar rules for that particular at-rule. +The `@` symbol, known in the CSS specifications as an ``, indicates the beginning of a CSS {{cssxref("at-rule")}}. Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The contents of each at-rule are interpreted according to the grammar rules for that particular at-rule. -Statement at-rules, such as {{cssxref("@import")}} and {{cssxref("@namespace")}} declarations, contain just a prelude. The semicolon ends the at-rule immediately for single-line at-rules. If the contents of the prelude are invalid according to the grammar for that at-rule, the at-rule is ignored, with the browser continuing to parse CSS after it encounters the next semi-colon. For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. +Statement at-rules, such as {{cssxref("@import")}} and {{cssxref("@namespace")}} declarations, contain just a prelude. The semicolon ends the at-rule immediately for [regular at-rules](en-US/docs/Web/CSS/At-rule#regular). If the contents of the prelude are invalid according to the grammar for that at-rule, the at-rule is ignored, with the browser continuing to parse CSS after it encounters the next semi-colon. For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. -If the parser encounter a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rule. Block at-rules, like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the completed at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else or inside of another block, to close the body of the at-rule. +```css +@import "assets/fonts.css" layer(fonts); +@namespace svg url(http://www.w3.org/2000/svg); +``` + +If the parser encounters a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rules. Block at-rules, also called [nested at-rules](en-US/docs/Web/CSS/At-rule#nested), like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else to close the body of the at-rule. -Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what, if anything, will invalidate the entire at-rule. The expected grammar for each at-rule and how errors are handled are documented on the respective at-rule page. The handling of invalid content depends on the error. +Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what, if anything, will invalidate the entire at-rule. The expected grammar for [each at-rule](/en-US/docs/Web/CSS/At-rule) and how errors are handled are documented on the respective at-rule page. The handling of invalid content depends on the error. -For the `@font-face` at-rule, including an unrelated descriptor, a valid font-face descriptor with an invalid value, or a property style declaration within an `@font-face` will not invalidate the font declaration. Only the invalid CSS is ignored. +The `@font-face` rule requires both a [`font-family`](/en-US/docs/Web/CSS/@font-face/font-family) and [`src`](/en-US/docs/Web/CSS/@font-face/src) descriptor. If either of these is omitted or invalid, the entire `@font-face` rule is invalid. Including an unrelated descriptor, any other valid font descriptor with an invalid value, or a property style declaration within the `@font-face` nested block will not invalidate the font declaration. As long as the font name and font source are included and valid, any invalid CSS within the at-rule block is ignored. -The grammar of the `@font-face` at rule is very different from the `@keyframe`, with the type of error impacting what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated in keyframe rules are ignored, but normal, supported properties will still be animated. Including a keyframe selector percentage value less than `0%`, greater than `100%`, or with the `%` sign omitted invalidates the keyframe selector list and therefore the style block is ignored, but an invalid keyframe selector doesn't not invalidate the entire `@keyframe`. Including styles between two keyframe selector block within a `@keyframe` invalidates the at-rule. +While the grammar of the `@keyframe` at-rule is very different, like the `@font-face` rule, the type of error impacts what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated in keyframe rules are ignored, but don't impact other styles declared in the same keyframe selector block. Including an invalid keyframe selector such as a percentage value less than `0%` or greater than `100%`, or a {{cssxref("number")}} omitting the `%`, invalidates the keyframe selector list and therefore the style block is ignored. An invalid keyframe selector only invalidates the invalid selector's style block; it does not invalidate the entire `@keyframe` declaration. Including styles between two keyframe selector blocks, on the other hand, will invalidate the entire `@keyframe` at-rule. -Some at-rules are almost always. The statement {{cssxref("@layer")}} contains just the prelude, ending with a semi-colon. Alternatively, this at-rule can also have layer styles nested between curly braces following the prelude. If the error is a missing closing curly brace, it is considered a logic error not a CSS error. In the case of a missing closing brace in `@layer`, the styles are assumed to be in the cascade layer that is defined in the at-rule's prelude. The CSS is considered valid; because there are no syntactic errors, the parser does not ignore any part. The `@layer` statement, whether it contains just a prelude statement ending with a semi-color or if it contains a body of declarations, as long as the layer name is not a [global CSS value](), the at-rule always creates at least one layer, though the layer may be an anonymous layer containing no styles. +Some at-rules are almost always valid. The {{cssxref("@layer")}} at rule comes in both regular and nested forms. The `@layer` statement syntax contains just the prelude, ending with a semi-colon. Alternatively, the nested syntax has layer styles nested between curly braces coming after the prelude. Omitting a closing curly brace may be a logic error but is not a syntax error. In the case of a missing closing brace in `@layer`, any styles coming after where the closing brace should have been are parsed as being in the cascade layer defined in the at-rule's prelude. The CSS is valid as there are no syntax errors; nothing is discarded. A syntax error may cause the named or anonymous layer to be empty, but the layer is still created. ### Errors in selector lists -There are many ways you might make a mistake writing a selector, but only invalid selectors cause a selector list to be invalid (See [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list) issues). +There are many ways you might make a mistake writing a selector, but only invalid selectors cause a selector list to be invalid (See [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list)). -If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element, respectively, that doesn't exist, it may be a logic error, but it's not an error the parser needs to handle. If, however, you have a typo in a pseudo-class or a pseudo-element, it might create an invalid selector, which is an error the parser will notice. +If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element, respectively, that doesn't exist, it may be a logic error, but it's not a syntax error. If, however, you have a typo in a pseudo-class or a pseudo-element, it might create an invalid selector, which is an error the parser needs to address. -If a selector list contains any selectors that are in the [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list), then the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-class, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list) or if the unknown selector is a [`-webkit-` prefixed pseudo-element](#webkit-exception), only the unknown selector is ignored as not matching anything. The selector list is not invalidated. +If a selector list contains any invalid selectors, then the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-class, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list) or if the unknown selector is a [`-webkit-` prefixed pseudo-element](#webkit-exception), only the unknown selector is ignored as not matching anything. The selector list is not invalidated. -If a selector list contains any invalid selectors outside of these exceptions, a single invalid or unsupported selector in the selector list will invalidate the entire rule. The entire selector block will be ignored. The browser will look for the closing curly brace and will continue parsing again from that point on. +If a selector list contains any invalid selectors outside of these exceptions, a single invalid or unsupported selector in the selector list will invalidate the entire rule and the entire selector block will be ignored. The browser will look for the closing curly brace and will continue parsing again from that point on. #### Webkit exception -Due to legacy issues from the overuse of browser-specific prefixes in selectors and in [property names and values](#vendor-prefixes), browsers avoid the invalidation of selector lists by treating all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a case-insensitive `-webkit-` prefix and don't end with `()` as valid. +Due to legacy issues from the overuse of browser-specific prefixes in selectors and in [property names (and values)](#vendor-prefixes), browsers avoid the invalidation of selector lists by treating all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a case-insensitive `-webkit-` prefix and don't end with `()` as valid. -This means that a pseudo-element like `::-webkit-works-only-in-samsung` will not invalidate a selector list, regardless of the browser. In such cases, the pseudo-element may not be recognized or supported by the browser, but it will not cause the entire selector list and it's associated style block to be ignored. On the other hand, the unknown prefixed selector with a function notation `::-webkit-imaginary-function()` will invalidate the entire selector list and the browser will ignore the entire selector block. +This means that a pseudo-element like `::-webkit-works-only-in-samsung` will not invalidate a selector list, regardless of the browser. In such cases, the pseudo-element may not be recognized or supported by the browser, but it will not cause the entire selector list and it's associated style block to be ignored. On the other hand, the unknown prefixed selector with a function notation `::-webkit-imaginary-function()` will invalidate the entire selector list, with the browser ignoring the entire selector block. ### Errors within CSS declaration blocks @@ -75,13 +80,13 @@ p { } ``` -The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last declaration in the block. The property missing the semi-colon is ignored, as is the property-value pair following it because the browser only continues parsing after a semi-colon or closing bracket is encountered. In the above CSS, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. +The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last one in the selector block. The property missing the semi-colon is ignored, as is the property-value pair following it because the browser only continues parsing after a semi-colon or closing bracket is encountered. In the above CSS, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. The parser ignores the property with an invalid value, and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is syntactically valid, it will be parsed and applied to the elements matching the selector. #### Vendor prefixes -Vendor-prefixed property names and property values, when not understood by a browser, are ignored. Only the single rule containing the invalid property or value is ignored. The parser looks for the next semi-colon or closing curly brace and then continues parsing from there. +Vendor-prefixed property names and property values, when not understood by a browser, are ignored. Only the individual rules containing an invalid property or value are ignored. The parser looks for the next semi-colon or closing curly brace and then continues parsing from there. You may come across legacy CSS that looks like the following: @@ -103,13 +108,13 @@ You may come across legacy CSS that looks like the following: } ``` -In both the declaration blocks above, the last declaration is valid. The parser ignores the declarations it doesn't understand as invalid. If the user agent does understand one of the prefixed declarations, for example, all browsers understand `display: flex;` and `border-radius: 50%;`, the values in the last, valid declaration are used, not because they are the valid ones, but rather due to the [cascade](/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#source_order) [order of appearance](/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) rule. +In both the declaration blocks, the last declaration is valid in all browsers. Parsers ignore the declarations they don't understand as invalid. For example, all browsers understand `display: flex;` and `border-radius: 50%;`. If the user agent doesn't understand one of the prefixed declarations, the values in the last, valid declarations are used. These last declared valid values are used due to the [cascade](/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#source_order) [order of appearance](/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) rule. -> **Note:** Avoid including prefixed properties or property values. If you must, declare the prefixed values before the valid, non-prefixed standard property-value pairs. +> **Note:** Avoid including prefixed properties or property values. If you must, declare the prefixed values before the valid, non-prefixed version. ### Errors with auto-closed endings -If a stylesheet — be it an external style sheet, selector blocks within an HTML {{HTMLElement("style")}} element, or inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, comment, etc. is still open, the parser will automatically close everything that was left unclosed. +If a stylesheet — be it an external style sheet, selector blocks within an HTML {{HTMLElement("style")}} element, or inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, or comment is still open, the parser will automatically close everything that was left unclosed. If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. For example, if you fail to close out an `@keyframe` declaration before closing your {{htmlelement("style")}}, the animation is still valid. @@ -121,11 +126,11 @@ If the content between the last semi-colon and the end of the stylesheet is vali ``` -The `move` animation is valid. Failing to properly close CSS statements doesn't necessarily make the statements invalid. That said, do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS you intended. +Here the `move` animation is valid. Failing to properly close CSS statements don't necessarily make the statements invalid. That said, do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS as you intended. #### Unclosed comments -Unclosed comments are logic errors, not syntax errors. If a comment starts with `/*` but is not closed, all CSS code until the closing comment `*/` is encountered will be treated as part of the comment. While an unclosed comment does not invalidate your CSS, it causes the CSS inside the comment to be ignored. +Unclosed comments are logic errors, not syntax errors. If a comment starts with `/*` but is not closed, all CSS code until the closing comment `*/` or the end of the stylesheet, whichever comes first, is part of the comment. While an unclosed comment does not invalidate your CSS, it causes the CSS inside the comment to be ignored. ```html example-bad ` tag closes the first comment and the quote at the end of the `style` attribute closes the second comment. +In this example, the two CSS comments are not closed, but the closing `` tag closes the first comment and the `style` attribute's close quote closes the second comment. ## Grammar check After each declaration, style rule, at-rule, etc. is parsed, the user agent checks to make sure the grammar is the expected grammar for that declaration. For example, if a property value is of the wrong data type or if a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid, and gets ignored. -### Invalid custom properties - Each CSS property accepts specific data types. For example, the {{cssxref("background-color")}} property accepts either a valid {{cssxref("<color>")}} or a CSS global keyword. When the value assigned to a property is of the wrong type, such as `background-color: 45deg`, the declaration is invalid and ignored. -Custom properties are generally considered valid when declared, but may create invalid CSS when accessed. The browser parses each custom property when encountered without regard to where the property is consumed. A custom property may be valid when declared while creating an invalid value when passed as a parameter for the {{cssxref("var")}} function for the grammar of where the `var()` function is found. -While invalid CSS is discarded with the property value falling back to the last valid value, an invalid computed custom property value is slightly different. If the custom property declaration was valid and the grammar of the property using that value is valid, the declaration is valid at computed time. The `var()` value substitution can still be invalid. +### Invalid custom properties + +Custom properties are generally considered valid when declared, but may create invalid CSS when accessed. The browser parses each custom property when encountered without regard to where the property is consumed. A custom property may be valid when declared while creating an invalid value when passed as a parameter of the {{cssxref("var")}} function for the grammar of where the `var()` function is found. + +While invalid CSS is discarded with the property value falling back to the last valid value, an invalid computed custom property value is slightly different. If the custom property declaration is valid and the grammar of the property using that value is valid, the declarations are valid at computed time. The `var()` value substitution, however, can still be invalid. -When a `var()` substitution is invalid, then the [initial](/en-US/docs/Web/CSS/initial_value) or [inherited](/en-US/docs/Web/CSS/Inheritance) value of the property is used; the declaration is not ignored. As the declaration was valid at compute time, the declaration is valid. This means the declaration is not ignored and the property does not remain the value of the previous valid value. Rather, the property is set to a new value, but possibly not the expected one. +When a `var()` substitution is invalid, then the [initial](/en-US/docs/Web/CSS/initial_value) or [inherited](/en-US/docs/Web/CSS/Inheritance) value of the property is used; the declaration is not ignored. As the declaration was valid at compute time, the declaration is considered valid. This means the declaration is not ignored and the value of the previous valid value does not cascade. Rather, the property is set to a new value, but possibly not the expected one. ```css example-bad :root { @@ -163,7 +169,7 @@ body { } ``` -In the above code, the custom property declaration is valid. The `background-color` declaration is also valid at compute time. However, when the browser substitutes the custom property in `var(--theme-color)` with `45deg`, the grammar is invalid. An {{cssxref("angle")}} is not a valid value `background-color`. In this case, the declaration is not ignored as invalid. Rather, when a custom property is of the wrong data-type, if the property is inheritable, the value is inherited from it's parent. If the property is not inheritable, the default initial value is used. In this case, the default background color is `transparent`. +In the above code, the custom property declaration is valid. The `background-color` declaration is also valid at compute time. However, when the browser substitutes the custom property in `var(--theme-color)` with `45deg` as a value of the `background-color` property, the grammar is invalid. An {{cssxref("angle")}} is not a valid `background-color` value. In this case, the declaration is not ignored as invalid. Rather, when a custom property is of the wrong type, if the property is inheritable, the value is inherited from its parent. If the property is not inheritable, the default initial value is used. In the case of `background-color`, the property value is not an inherited value, so the inital value of `transparent` is used. To better control the way custom properties fall back, use the {{cssxref("@property")}} at-rule to define the initial value of the property: From ee42a504bff3e8966413951ce36b3ca3a18c04e7 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Fri, 15 Dec 2023 00:22:22 -0800 Subject: [PATCH 31/43] trailing spaces Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/css/css_syntax/error_handling/index.md | 4 ++-- files/en-us/web/css/css_syntax/index.md | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 1fd94345b6b0109..efcbefb5fad6d70 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -30,14 +30,14 @@ After parsing each declaration, style rule, at-rule, and so on, the browser chec The `@` symbol, known in the CSS specifications as an ``, indicates the beginning of a CSS {{cssxref("at-rule")}}. Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The contents of each at-rule are interpreted according to the grammar rules for that particular at-rule. -Statement at-rules, such as {{cssxref("@import")}} and {{cssxref("@namespace")}} declarations, contain just a prelude. The semicolon ends the at-rule immediately for [regular at-rules](en-US/docs/Web/CSS/At-rule#regular). If the contents of the prelude are invalid according to the grammar for that at-rule, the at-rule is ignored, with the browser continuing to parse CSS after it encounters the next semi-colon. For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. +Statement at-rules, such as {{cssxref("@import")}} and {{cssxref("@namespace")}} declarations, contain just a prelude. The semicolon ends the at-rule immediately for [regular at-rules](/en-US/docs/Web/CSS/At-rule#regular). If the contents of the prelude are invalid according to the grammar for that at-rule, the at-rule is ignored, with the browser continuing to parse CSS after it encounters the next semi-colon. For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. ```css @import "assets/fonts.css" layer(fonts); @namespace svg url(http://www.w3.org/2000/svg); ``` -If the parser encounters a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rules. Block at-rules, also called [nested at-rules](en-US/docs/Web/CSS/At-rule#nested), like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else to close the body of the at-rule. +If the parser encounters a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rules. Block at-rules, also called [nested at-rules](/en-US/docs/Web/CSS/At-rule#nested), like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else to close the body of the at-rule. Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what, if anything, will invalidate the entire at-rule. The expected grammar for [each at-rule](/en-US/docs/Web/CSS/At-rule) and how errors are handled are documented on the respective at-rule page. The handling of invalid content depends on the error. diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md index 8c349e8f43e3ac7..6ecc4d2a56847e2 100644 --- a/files/en-us/web/css/css_syntax/index.md +++ b/files/en-us/web/css/css_syntax/index.md @@ -46,10 +46,9 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru - [CSS syntax error handling](/en-US/docs/Web/CSS/CSS_syntax/Error_handling) - : Overview of how the user-agent handles invalid CSS - - [Learn CSS first steps: CSS syntax](/en-US/docs/Learn/CSS/First_steps/What_is_CSS#css_syntax) - - : Introductory guide to CSS, including an introcution to CSS syntax. + - : Introductory guide to CSS, including an introcution to CSS syntax. ## Related concepts From 55d3ad95aa8a079e8f40bd90f0dd5ae98ad9933c Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Fri, 15 Dec 2023 00:22:52 -0800 Subject: [PATCH 32/43] Update files/en-us/web/css/css_syntax/error_handling/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/css/css_syntax/error_handling/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index efcbefb5fad6d70..8b2d9f3a6dd1b6a 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -151,7 +151,6 @@ After each declaration, style rule, at-rule, etc. is parsed, the user agent chec Each CSS property accepts specific data types. For example, the {{cssxref("background-color")}} property accepts either a valid {{cssxref("<color>")}} or a CSS global keyword. When the value assigned to a property is of the wrong type, such as `background-color: 45deg`, the declaration is invalid and ignored. - ### Invalid custom properties Custom properties are generally considered valid when declared, but may create invalid CSS when accessed. The browser parses each custom property when encountered without regard to where the property is consumed. A custom property may be valid when declared while creating an invalid value when passed as a parameter of the {{cssxref("var")}} function for the grammar of where the `var()` function is found. From 84df878a678c4554021bed49568a028a15175533 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Fri, 15 Dec 2023 00:27:34 -0800 Subject: [PATCH 33/43] Update files/en-us/web/css/css_syntax/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/css/css_syntax/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md index 6ecc4d2a56847e2..bc1ac20937a2135 100644 --- a/files/en-us/web/css/css_syntax/index.md +++ b/files/en-us/web/css/css_syntax/index.md @@ -46,6 +46,7 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru - [CSS syntax error handling](/en-US/docs/Web/CSS/CSS_syntax/Error_handling) - : Overview of how the user-agent handles invalid CSS + - [Learn CSS first steps: CSS syntax](/en-US/docs/Learn/CSS/First_steps/What_is_CSS#css_syntax) - : Introductory guide to CSS, including an introcution to CSS syntax. From 94969cdbf309283fe45281be23ec410ea41000aa Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Mon, 18 Dec 2023 07:20:18 +0000 Subject: [PATCH 34/43] Small punctuation fixes --- files/en-us/web/css/@charset/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/css/@charset/index.md b/files/en-us/web/css/@charset/index.md index 306e2b55999cb77..f69aca5bf892ab1 100644 --- a/files/en-us/web/css/@charset/index.md +++ b/files/en-us/web/css/@charset/index.md @@ -17,13 +17,13 @@ The `@charset` rule must be the first element in the style sheet and not be prec This at-rule is useful when using non-{{Glossary("ASCII")}} characters in some CSS properties, like {{ cssxref("content") }}. -As there are several ways to define the character encoding of a style sheet, the browser will try the following methods in the following order (and stop as soon as one yields a result) : +As there are several ways to define the character encoding of a style sheet, the browser will try the following methods in the following order (and stop as soon as one yields a result): 1. The value of the [Unicode byte-order](https://en.wikipedia.org/wiki/Byte_order_mark) character placed at the beginning of the file. 2. The value given by the `charset` attribute of the `Content-Type:` HTTP header or the equivalent in the protocol used to serve the style sheet. 3. The `@charset` CSS at-rule. 4. Use the character encoding defined by the referring document: the `charset` attribute of the {{ HTMLElement("link") }} element. This method is obsolete and should not be used. -5. Assume that the document is UTF-8 +5. Assume that the document is UTF-8. ## Syntax From 362058ec8ad20fba1d666ae16a9c234971e30218 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Mon, 18 Dec 2023 11:23:18 -0800 Subject: [PATCH 35/43] Apply suggestions from code review Co-authored-by: Chris Mills --- files/en-us/web/css/@charset/index.md | 9 ++- .../css/css_syntax/error_handling/index.md | 62 +++++++++++-------- files/en-us/web/css/css_syntax/index.md | 6 +- files/en-us/web/css/custom-ident/index.md | 10 +-- 4 files changed, 50 insertions(+), 37 deletions(-) diff --git a/files/en-us/web/css/@charset/index.md b/files/en-us/web/css/@charset/index.md index f69aca5bf892ab1..f27fb1cfbb13cc1 100644 --- a/files/en-us/web/css/@charset/index.md +++ b/files/en-us/web/css/@charset/index.md @@ -7,9 +7,14 @@ browser-compat: css.at-rules.charset {{CSSRef}} -The **`@charset`** [CSS](/en-US/docs/Web/CSS) rule specifies the character encoding used in the style sheet. Although the first character in `@charset` is the `@` symbol, it is not an [at-rule](/en-US/docs/Web/CSS/At-rule). The [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module deprecates this rule, defining it as an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked, but it is [fully supported in all browsers](#browser-compatibility). +The **`@charset`** [CSS](/en-US/docs/Web/CSS) rule specifies the character encoding used in the style sheet. Although the first character in `@charset` is the `@` symbol, it is not an [at-rule](/en-US/docs/Web/CSS/At-rule). The [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module deprecates this rule, defining it as an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked, but it is [fully supported in all browsers](#browser_compatibility). -The `@charset` rule must be the first element in the style sheet and not be preceded by any character; as it is not a [nested statement](/en-US/docs/Web/CSS/Syntax#nested_statements), it cannot be used inside [conditional group at-rules](/en-US/docs/Web/CSS/At-rule#conditional_group_rules). If several `@charset` at-rules are defined, only the first one is used, and it cannot be used inside a `style` attribute on an HTML element or inside the {{ HTMLElement("style") }} element where the character set of the HTML page is relevant. +The following assertions apply to valid `@charset` usage: + +- The `@charset` rule must be the first element in the style sheet and not be preceded by any character. +- `@charset` is not a [nested statement](/en-US/docs/Web/CSS/Syntax#nested_statements) and therefore cannot be used inside [conditional group at-rules](/en-US/docs/Web/CSS/At-rule#conditional_group_rules). +- If several `@charset` at-rules are defined, only the first one is used. +- `@charset` cannot be used inside a `style` attribute on an HTML element or inside the {{ HTMLElement("style") }} element where the character set of the HTML page is relevant. ```css @charset "utf-8"; diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 8b2d9f3a6dd1b6a..1093f44273a3496 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -12,9 +12,13 @@ This guide discusses how CSS {{glossary("parser", "parsers")}} discard invalid C ## CSS parser errors -When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the lines containing the errors, discarding the minimum amount of content before returning to {{glossary("parse", "parsing")}} the CSS as normal. The "error recovery" is just the ignoring or skipping of invalid content. This recovery from errors allows a browser to discard the line containing the unrecognized content. +When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the line containing the errors, discarding the minimum amount of CSS code before returning to {{glossary("parse", "parsing")}} the CSS as normal. The "error recovery" is just the ignoring or skipping of invalid content. -The fact that browsers ignore invalid code enables the use of new CSS features without worrying about anything being broken in older browsers. A browser may not recognize a new feature, but that is okay. The discarding of invalid content without throwing an error also allows for both old and new syntaxes to coexist, in that order. Browsers render the old syntax until they recognize the new syntax as valid. Because browsers ignore invalid CSS, the valid fallbacks don't get overwritten by the new CSS that follows it that is perceived as invalid. +The fact that browsers ignore invalid code enables the use of new CSS features without worrying about anything being broken in older browsers. A browser may not recognize a new feature, but that is okay. The discarding of invalid content without throwing an error allows both old and new syntaxes to coexist in the same ruleset, although bear in mind that they should be specified in that order. For example: + +(include a syntax block here showing an example) + +Browsers will render the old syntax until they recognize the new syntax as valid, at which point the new syntax will override the old. Until then, the valid fallback won't get overwritten by the new CSS, because the browser perceives it as invalid. The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some common error situations are listed below: @@ -28,7 +32,7 @@ After parsing each declaration, style rule, at-rule, and so on, the browser chec ### At-rule errors -The `@` symbol, known in the CSS specifications as an ``, indicates the beginning of a CSS {{cssxref("at-rule")}}. Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint; everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The contents of each at-rule are interpreted according to the grammar rules for that particular at-rule. +The `@` symbol, known in CSS specifications as an ``, indicates the beginning of a CSS {{cssxref("at-rule")}}. Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint. Everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The content of each at-rule is interpreted according to the grammar rules for that particular at-rule. Statement at-rules, such as {{cssxref("@import")}} and {{cssxref("@namespace")}} declarations, contain just a prelude. The semicolon ends the at-rule immediately for [regular at-rules](/en-US/docs/Web/CSS/At-rule#regular). If the contents of the prelude are invalid according to the grammar for that at-rule, the at-rule is ignored, with the browser continuing to parse CSS after it encounters the next semi-colon. For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. @@ -37,37 +41,37 @@ Statement at-rules, such as {{cssxref("@import")}} and {{cssxref("@namespace")}} @namespace svg url(http://www.w3.org/2000/svg); ``` -If the parser encounters a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rules. Block at-rules, also called [nested at-rules](/en-US/docs/Web/CSS/At-rule#nested), like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by anything else to close the body of the at-rule. +If the parser encounters a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rule. Block at-rules, also called [nested at-rules](/en-US/docs/Web/CSS/At-rule#nested), like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by any other curly braces: this closes the body of the at-rule. Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what, if anything, will invalidate the entire at-rule. The expected grammar for [each at-rule](/en-US/docs/Web/CSS/At-rule) and how errors are handled are documented on the respective at-rule page. The handling of invalid content depends on the error. -The `@font-face` rule requires both a [`font-family`](/en-US/docs/Web/CSS/@font-face/font-family) and [`src`](/en-US/docs/Web/CSS/@font-face/src) descriptor. If either of these is omitted or invalid, the entire `@font-face` rule is invalid. Including an unrelated descriptor, any other valid font descriptor with an invalid value, or a property style declaration within the `@font-face` nested block will not invalidate the font declaration. As long as the font name and font source are included and valid, any invalid CSS within the at-rule block is ignored. +For example, the `@font-face` rule requires both a [`font-family`](/en-US/docs/Web/CSS/@font-face/font-family) and [`src`](/en-US/docs/Web/CSS/@font-face/src) descriptor. If either of these is omitted or invalid, the entire `@font-face` rule is invalid. Including an unrelated descriptor, any other valid font descriptor with an invalid value, or a property style declaration within the `@font-face` nested block will not invalidate the font declaration. As long as the font name and font source are included and valid, any invalid CSS within the at-rule is ignored, but the `@font-face` block is still parsed. -While the grammar of the `@keyframe` at-rule is very different, like the `@font-face` rule, the type of error impacts what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated in keyframe rules are ignored, but don't impact other styles declared in the same keyframe selector block. Including an invalid keyframe selector such as a percentage value less than `0%` or greater than `100%`, or a {{cssxref("number")}} omitting the `%`, invalidates the keyframe selector list and therefore the style block is ignored. An invalid keyframe selector only invalidates the invalid selector's style block; it does not invalidate the entire `@keyframe` declaration. Including styles between two keyframe selector blocks, on the other hand, will invalidate the entire `@keyframe` at-rule. +While the grammar of the `@keyframe` at-rule is very different from the `@font-face` rule grammar, the type of error still impacts what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated are ignored in keyframe rules, but they don't impact other styles declared in the same keyframe selector block. Including an invalid keyframe selector (such as a percentage value less than `0%` or greater than `100%`, or a {{cssxref("number")}} omitting the `%`) invalidates the keyframe selector list and therefore the style block is ignored. An invalid keyframe selector only invalidates the invalid selector's style block; it does not invalidate the entire `@keyframe` declaration. Including styles between two keyframe selector blocks, on the other hand, will invalidate the entire `@keyframe` at-rule. -Some at-rules are almost always valid. The {{cssxref("@layer")}} at rule comes in both regular and nested forms. The `@layer` statement syntax contains just the prelude, ending with a semi-colon. Alternatively, the nested syntax has layer styles nested between curly braces coming after the prelude. Omitting a closing curly brace may be a logic error but is not a syntax error. In the case of a missing closing brace in `@layer`, any styles coming after where the closing brace should have been are parsed as being in the cascade layer defined in the at-rule's prelude. The CSS is valid as there are no syntax errors; nothing is discarded. A syntax error may cause the named or anonymous layer to be empty, but the layer is still created. +Some at-rules are almost always valid. The {{cssxref("@layer")}} at-rule comes in both regular and nested forms. The `@layer` statement syntax contains just the prelude, ending with a semi-colon. Alternatively, the nested syntax has layer styles nested between curly braces coming after the prelude. Omitting a closing curly brace may be a logic error but is not a syntax error. In the case of a missing closing brace in `@layer`, any styles coming after where the closing brace should have been are parsed as being in the cascade layer defined in the at-rule's prelude. The CSS is valid as there are no syntax errors; nothing is discarded. A syntax error may cause the named or anonymous layer to be empty, but the layer is still created. ### Errors in selector lists There are many ways you might make a mistake writing a selector, but only invalid selectors cause a selector list to be invalid (See [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list)). -If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, element or custom-element, respectively, that doesn't exist, it may be a logic error, but it's not a syntax error. If, however, you have a typo in a pseudo-class or a pseudo-element, it might create an invalid selector, which is an error the parser needs to address. +If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, or element (or custom element) that doesn't exist, it may be a logic error but it's not a syntax error. However, if you have a typo in a pseudo-class or a pseudo-element, it might create an invalid selector, which is an error the parser needs to address. If a selector list contains any invalid selectors, then the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-class, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list) or if the unknown selector is a [`-webkit-` prefixed pseudo-element](#webkit-exception), only the unknown selector is ignored as not matching anything. The selector list is not invalidated. -If a selector list contains any invalid selectors outside of these exceptions, a single invalid or unsupported selector in the selector list will invalidate the entire rule and the entire selector block will be ignored. The browser will look for the closing curly brace and will continue parsing again from that point on. +Outside of these exceptions, a single invalid or unsupported selector in the selector list will invalidate the entire rule and the entire selector block will be ignored. The browser will then look for the closing curly brace and continue parsing from that point onwards. -#### Webkit exception +#### `-webkit-` exception -Due to legacy issues from the overuse of browser-specific prefixes in selectors and in [property names (and values)](#vendor-prefixes), browsers avoid the invalidation of selector lists by treating all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a case-insensitive `-webkit-` prefix and don't end with `()` as valid. +Due to legacy issues from the overuse of browser-specific prefixes in selectors and [property names (and values)](#vendor-prefixes), browsers avoid excessive invalidation of selector lists by treating all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a case-insensitive `-webkit-` prefix and don't end with `()` as valid. -This means that a pseudo-element like `::-webkit-works-only-in-samsung` will not invalidate a selector list, regardless of the browser. In such cases, the pseudo-element may not be recognized or supported by the browser, but it will not cause the entire selector list and it's associated style block to be ignored. On the other hand, the unknown prefixed selector with a function notation `::-webkit-imaginary-function()` will invalidate the entire selector list, with the browser ignoring the entire selector block. +This means that a pseudo-element like `::-webkit-works-only-in-samsung` will not invalidate a selector list, regardless of which browser the code is running in. In such cases, the pseudo-element may not be recognized or supported by the browser, but it will not cause the entire selector list and its associated style block to be ignored. On the other hand, an unknown prefixed selector with a function notation of `::-webkit-imaginary-function()` will invalidate the entire selector list, and the browser will ignore the entire selector block. ### Errors within CSS declaration blocks -When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parses or interprets a list of declarations, unknown syntax at any point causes the browser's parser to discard only that specific rule. It then continues parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. +When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parses or interprets a list of declarations, unknown syntax at any point causes the browser's parser to discard only the current declaration. It then continues parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. -This example contains an error. The parser ignores the error (and the comments), seeking forward until it encounters a semi-colon, then restarts parsing: +This example contains an error. The parser ignores the error (and the comments), seeks forward until it encounters a semi-colon, then restarts parsing: ```css-nolint bad p { @@ -80,13 +84,13 @@ p { } ``` -The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last one in the selector block. The property missing the semi-colon is ignored, as is the property-value pair following it because the browser only continues parsing after a semi-colon or closing bracket is encountered. In the above CSS, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. +The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last one in the selector block. The property missing the semi-colon is ignored, as is the property-value pair following it because the browser only continues parsing after a semi-colon or closing bracket is encountered. Specifically, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. -The parser ignores the property with an invalid value, and starts parsing again after it encounters the next semi-colon. The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is syntactically valid, it will be parsed and applied to the elements matching the selector. +The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is syntactically valid, it will be parsed and applied to the elements matching the selector. #### Vendor prefixes -Vendor-prefixed property names and property values, when not understood by a browser, are ignored. Only the individual rules containing an invalid property or value are ignored. The parser looks for the next semi-colon or closing curly brace and then continues parsing from there. +Vendor-prefixed property names and property values, when not understood by a browser, are treated as invalid and ignored. Only the individual rules containing an invalid property or value are ignored. The parser looks for the next semi-colon or closing curly brace and then continues parsing from there. You may come across legacy CSS that looks like the following: @@ -108,15 +112,17 @@ You may come across legacy CSS that looks like the following: } ``` -In both the declaration blocks, the last declaration is valid in all browsers. Parsers ignore the declarations they don't understand as invalid. For example, all browsers understand `display: flex;` and `border-radius: 50%;`. If the user agent doesn't understand one of the prefixed declarations, the values in the last, valid declarations are used. These last declared valid values are used due to the [cascade](/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#source_order) [order of appearance](/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) rule. +In this example, the last declaration in each block is valid in all browsers — `display: flex;` and `border-radius: 50%;`. Because of the [cascade](/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#source_order) [order of appearance](/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) rule, browsers will apply any prefixed declarations they understand, and then override those values with the standard unprefixed version. -> **Note:** Avoid including prefixed properties or property values. If you must, declare the prefixed values before the valid, non-prefixed version. +> **Note:** Avoid including prefixed properties or property values where possible. If you must use them, declare the prefixed versions before the non-prefixed version as shown above. ### Errors with auto-closed endings -If a stylesheet — be it an external style sheet, selector blocks within an HTML {{HTMLElement("style")}} element, or inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute — ends while a rule, declaration, function, string, or comment is still open, the parser will automatically close everything that was left unclosed. +If a stylesheet ends while a rule, declaration, function, string, or comment is still open, the parser will automatically close everything that was left unclosed. -If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. For example, if you fail to close out an `@keyframe` declaration before closing your {{htmlelement("style")}}, the animation is still valid. +> **Note:** This is true of external style sheets, selector blocks within an HTML {{HTMLElement("style")}} element, and inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. + +If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. For example, if you fail to close out a `@keyframe` declaration before closing your {{htmlelement("style")}}, the animation is still valid. ```html-nolint example-bad ``` -Here the `move` animation is valid. Failing to properly close CSS statements don't necessarily make the statements invalid. That said, do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS as you intended. +Here the `move` animation is valid. Failing to properly close CSS statements doesn't necessarily make the statements invalid. That said, do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS as you intended. #### Unclosed comments @@ -147,17 +153,19 @@ In this example, the two CSS comments are not closed, but the closing `` ## Grammar check -After each declaration, style rule, at-rule, etc. is parsed, the user agent checks to make sure the grammar is the expected grammar for that declaration. For example, if a property value is of the wrong data type or if a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid, and gets ignored. +After parsing each declaration, style rule, at-rule, etc., the user agent checks to make sure the grammar follows the rules for that declaration. For example, if a property value is of the wrong data type or a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid and gets ignored. -Each CSS property accepts specific data types. For example, the {{cssxref("background-color")}} property accepts either a valid {{cssxref("<color>")}} or a CSS global keyword. When the value assigned to a property is of the wrong type, such as `background-color: 45deg`, the declaration is invalid and ignored. +Each CSS property accepts specific data types. For example, the {{cssxref("background-color")}} property accepts either a valid {{cssxref("<color>")}} or a CSS global keyword. When the value assigned to a property is of the wrong type, such as `background-color: 45deg`, the declaration is invalid and therefore ignored. ### Invalid custom properties -Custom properties are generally considered valid when declared, but may create invalid CSS when accessed. The browser parses each custom property when encountered without regard to where the property is consumed. A custom property may be valid when declared while creating an invalid value when passed as a parameter of the {{cssxref("var")}} function for the grammar of where the `var()` function is found. +Custom properties are generally considered valid when declared, but may create invalid CSS when accessed, i.e. they may be used as a value (via the {{cssxref("var")}} function) for a property that does not accept that value type. The browser parses each custom property when encountered without regard to where the property is consumed. + +Generally, when a property value is invalid, the declaration is ignored and the property falls back to the last valid value. Invalid computed custom property values, however, work slightly differently. -While invalid CSS is discarded with the property value falling back to the last valid value, an invalid computed custom property value is slightly different. If the custom property declaration is valid and the grammar of the property using that value is valid, the declarations are valid at computed time. The `var()` value substitution, however, can still be invalid. +When a `var()` substitution is invalid, the declaration is not ignored and the [initial](/en-US/docs/Web/CSS/initial_value) or [inherited](/en-US/docs/Web/CSS/Inheritance) value of the property is used instead. The property is set to a new value, but possibly not the expected one. -When a `var()` substitution is invalid, then the [initial](/en-US/docs/Web/CSS/initial_value) or [inherited](/en-US/docs/Web/CSS/Inheritance) value of the property is used; the declaration is not ignored. As the declaration was valid at compute time, the declaration is considered valid. This means the declaration is not ignored and the value of the previous valid value does not cascade. Rather, the property is set to a new value, but possibly not the expected one. +Let's look at an example to illustrate this behavior: ```css example-bad :root { diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md index bc1ac20937a2135..ca3370d950c7133 100644 --- a/files/en-us/web/css/css_syntax/index.md +++ b/files/en-us/web/css/css_syntax/index.md @@ -41,15 +41,15 @@ The module explicitly states that {{cssxref("@charset")}} is not an actual at-ru - [Value definition syntax](/en-US/docs/Web/CSS/Value_definition_syntax) - - : The formal grammar for defining valid values for CSS properties and functions, along with semantic constraints. A guide for understanding CSS component value types, combinators, and multipliers. + - : Explains the formal grammar for defining valid values for CSS properties and functions, along with semantic constraints. A guide for understanding CSS component value types, combinators, and multipliers. - [CSS syntax error handling](/en-US/docs/Web/CSS/CSS_syntax/Error_handling) - - : Overview of how the user-agent handles invalid CSS + - : Overview of how the user agent handles invalid CSS. - [Learn CSS first steps: CSS syntax](/en-US/docs/Learn/CSS/First_steps/What_is_CSS#css_syntax) - - : Introductory guide to CSS, including an introcution to CSS syntax. + - : Introductory guide to CSS, including an introduction to CSS syntax. ## Related concepts diff --git a/files/en-us/web/css/custom-ident/index.md b/files/en-us/web/css/custom-ident/index.md index 22162a8f3a63350..5315f24ed79b1ca 100644 --- a/files/en-us/web/css/custom-ident/index.md +++ b/files/en-us/web/css/custom-ident/index.md @@ -24,7 +24,7 @@ The syntax of `` is similar to CSS identifiers (such as property n - an [escaped character](#escaping-characters) (preceded by a backslash, `\`), - a [Unicode](https://en.wikipedia.org/wiki/Unicode) character (in the format of a backslash, `\`, followed by one to six hexadecimal digits, representing its Unicode code point) -Note that `id1`, `Id1`, `iD1` and `ID1` are all different identifiers as they are [case-sensitive](https://en.wikipedia.org/wiki/Case_sensitivity). +Note that `id1`, `Id1`, `iD1`, and `ID1` are all different identifiers as they are [case-sensitive](https://en.wikipedia.org/wiki/Case_sensitivity). ### Escaping characters @@ -37,11 +37,11 @@ In CSS, there are several ways to escape a character. Escape sequences start wit Examples: -- "&B" can be written as `\26 B` and `\000026B`. -- "hi.there" can be written as `hi\.there` and `hi\002Ethere`. -- "toto?" can be written as`toto\?`, `toto\3F`, or `toto\00003F` +- "&B" can be written as `\26 B` or `\000026B`. +- "hi.there" can be written as `hi\.there` or `hi\002Ethere`. +- "toto?" can be written as `toto\?`, `toto\3F`, or `toto\00003F`. -To include actual white space after an escape sequence, include two white spaces in the escape sequence . +To include actual white space after an escape sequence, include two white spaces in the escape sequence. ### Forbidden values From 48612a6eab3af647c1125d8e3b311f058c215d46 Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Mon, 18 Dec 2023 11:24:50 -0800 Subject: [PATCH 36/43] header for at-rule --- files/en-us/web/css/css_syntax/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md index ca3370d950c7133..179654836eb0b2c 100644 --- a/files/en-us/web/css/css_syntax/index.md +++ b/files/en-us/web/css/css_syntax/index.md @@ -10,6 +10,7 @@ spec-urls: https://drafts.csswg.org/css-syntax The **CSS syntax** module describes, in general terms, the structure and syntax of cascading stylesheets, or CSS. It defines CSS as the language for describing the rendering of structured documents (such as HTML and XML), on the web and elsewhere. This module doesn't define any properties, {{cssxref("css_types", "data types")}}, {{cssxref("css_functions", "functions")}}, or {{cssxref("at-rule", "at-rules")}}. Rather, it elaborates on how all of these features should be defined and how user agents should parse CSS. +## At-rules The module explicitly states that {{cssxref("@charset")}} is not an actual at-rule, but rather an unrecognized legacy rule that should be omitted when a stylesheet is grammar-checked. From 33c1b0d5ab3392bfdae7614d5cdcf4c5303db2d8 Mon Sep 17 00:00:00 2001 From: estelle Date: Mon, 18 Dec 2023 12:05:10 -0800 Subject: [PATCH 37/43] updates based on review feedback --- .../css/css_syntax/error_handling/index.md | 23 +++++++++++-------- files/en-us/web/css/css_syntax/index.md | 7 ++++-- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 1093f44273a3496..9d52ca10be86618 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -6,9 +6,9 @@ page-type: guide {{CSSRef}} -When an error exists in CSS, such as an invalid value or a missing semicolon, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser (or other user-agent) will gracefully recover. Browsers don't provide CSS-related alerts or otherwise indicate errors have occurred in styles. They just discard invalid content and parse subsequent valid styles. This is a feature of CSS, not a bug. +When an error exists in CSS, such as an invalid value or a missing semicolon, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser (or other user agent) will gracefully recover. Browsers don't provide CSS-related alerts or otherwise indicate errors have occurred in styles. They just discard invalid content and parse subsequent valid styles. This is a feature of CSS, not a bug. -This guide discusses how CSS {{glossary("parser", "parsers")}} discard invalid CSS. +This guide discusses how CSS {{glossary("parser", "parsers")}} discards invalid CSS. ## CSS parser errors @@ -16,17 +16,22 @@ When a CSS error is encountered, the browser's {{glossary("parser")}} ignores th The fact that browsers ignore invalid code enables the use of new CSS features without worrying about anything being broken in older browsers. A browser may not recognize a new feature, but that is okay. The discarding of invalid content without throwing an error allows both old and new syntaxes to coexist in the same ruleset, although bear in mind that they should be specified in that order. For example: -(include a syntax block here showing an example) +```css +div { + display: inline-flex; + display: inline flex; +} +``` -Browsers will render the old syntax until they recognize the new syntax as valid, at which point the new syntax will override the old. Until then, the valid fallback won't get overwritten by the new CSS, because the browser perceives it as invalid. +Browsers will render the old syntax until they recognize the new syntax as valid, at which point the new syntax will override the old. Until then, the valid fallback won't get overwritten by the new CSS, because the browser perceives it as invalid. (See ) The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some common error situations are listed below: - For [errors in at-rules](#at-rule_errors), whether a single line or the entire at-rule is ignored (fails) depends on the at-rule and the type of error. - If the [error is an invalid selector](#errors_in_selector_lists), the entire declaration block is ignored. -- An [error due to a missing semi-colon](#errors_within_css_declaration_blocks) between property declarations causes an invalid value, in which case, the property-value declaration is ignored. +- An [error due to a missing semi-colon](#errors_within_css_declaration_blocks) between property declarations causes an invalid value, in which case, multiple property-value declarations are ignored. - If the [error is a property name or value](#errors_within_css_declaration_blocks), such as an unrecognized property name or invalid data type, the property-value declaration is ignored. -- If the [error is due to a missing end-bracket](#auto-closed_endings), the extent of what is ignored depends on the browser's ability to parse the error as nested CSS. +- If the [error is due to a missing end-bracket](#errors_with_auto-closed_endings), the extent of what is ignored depends on the browser's ability to parse the error as nested CSS. After parsing each declaration, style rule, at-rule, and so on, the browser checks the parsed content against its expected [grammar](#grammar_check) for that construct. If the content does not match the expected grammar for that construct, the browser considers it invalid and ignores it. @@ -57,7 +62,7 @@ There are many ways you might make a mistake writing a selector, but only invali If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, or element (or custom element) that doesn't exist, it may be a logic error but it's not a syntax error. However, if you have a typo in a pseudo-class or a pseudo-element, it might create an invalid selector, which is an error the parser needs to address. -If a selector list contains any invalid selectors, then the entire style block is ignored. There are exceptions: if the invalid selector is within the {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-class, which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list) or if the unknown selector is a [`-webkit-` prefixed pseudo-element](#webkit-exception), only the unknown selector is ignored as not matching anything. The selector list is not invalidated. +If a selector list contains any invalid selectors, then the entire style block is ignored. There are exceptions: if the invalid selector is within an {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-class (which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list)) or if the unknown selector is a [`-webkit-` prefixed pseudo-element](#-webkit-_exception), only the unknown selector is ignored as not matching anything. The selector list is not invalidated. Outside of these exceptions, a single invalid or unsupported selector in the selector list will invalidate the entire rule and the entire selector block will be ignored. The browser will then look for the closing curly brace and continue parsing from that point onwards. @@ -136,7 +141,7 @@ Here the `move` animation is valid. Failing to properly close CSS statements doe #### Unclosed comments -Unclosed comments are logic errors, not syntax errors. If a comment starts with `/*` but is not closed, all CSS code until the closing comment `*/` or the end of the stylesheet, whichever comes first, is part of the comment. While an unclosed comment does not invalidate your CSS, it causes the CSS inside the comment to be ignored. +Unclosed comments are logic errors, not syntax errors. If a comment starts with `/*` but is not closed, all CSS code until a closing delimiter (`*/`) in a subsequent comment or the end of the stylesheet, whichever comes first, is part of the comment. While an unclosed comment does not invalidate your CSS, it causes the CSS following the opening delimiter (`/*`) to be ignored. ```html example-bad