From e03cdadd99259770aefef875de5a988aeda6aff0 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Sat, 15 Aug 2026 10:03:14 +1000 Subject: [PATCH 1/2] FF154 CSSNumericArray and CSSUnparsedValue fixes (#45137) --- .../web/api/cssnumericarray/entries/index.md | 57 +++++++++ .../web/api/cssnumericarray/foreach/index.md | 67 ++++++++++ files/en-us/web/api/cssnumericarray/index.md | 49 +++++++- .../web/api/cssnumericarray/keys/index.md | 57 +++++++++ .../web/api/cssnumericarray/length/index.md | 23 +++- .../web/api/cssnumericarray/values/index.md | 57 +++++++++ .../cssunparsedvalue/index.md | 30 ++++- .../web/api/cssunparsedvalue/entries/index.md | 30 +++-- .../web/api/cssunparsedvalue/foreach/index.md | 31 +++-- files/en-us/web/api/cssunparsedvalue/index.md | 118 +++++++++++++++--- .../web/api/cssunparsedvalue/keys/index.md | 25 +++- .../web/api/cssunparsedvalue/length/index.md | 12 +- .../web/api/cssunparsedvalue/values/index.md | 25 +++- 13 files changed, 517 insertions(+), 64 deletions(-) create mode 100644 files/en-us/web/api/cssnumericarray/entries/index.md create mode 100644 files/en-us/web/api/cssnumericarray/foreach/index.md create mode 100644 files/en-us/web/api/cssnumericarray/keys/index.md create mode 100644 files/en-us/web/api/cssnumericarray/values/index.md diff --git a/files/en-us/web/api/cssnumericarray/entries/index.md b/files/en-us/web/api/cssnumericarray/entries/index.md new file mode 100644 index 000000000000000..84ce1ad8a3e8f4c --- /dev/null +++ b/files/en-us/web/api/cssnumericarray/entries/index.md @@ -0,0 +1,57 @@ +--- +title: "CSSNumericArray: entries() method" +short-title: entries() +slug: Web/API/CSSNumericArray/entries +page-type: web-api-instance-method +browser-compat: api.CSSNumericArray.entries +--- + +{{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} + +The **`entries()`** method of the {{domxref("CSSNumericArray")}} interface returns a new _array iterator_ that yields `[index, value]` pairs for each item in the object. + +## Syntax + +```js-nolint +entries() +``` + +### Parameters + +None. + +### Return value + +A new [iterable iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + +## Examples + +### Iterating over index/value pairs + +```js +const sum = new CSSMathSum(CSS.px(10), CSS.em(5), CSS.percent(50)); + +for (const [index, value] of sum.values.entries()) { + console.log(index, value.toString()); +} +// 0 "10px" +// 1 "5em" +// 2 "50%" +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("CSSNumericArray.forEach()")}} +- {{domxref("CSSNumericArray.keys()")}} +- {{domxref("CSSNumericArray.length")}} +- {{domxref("CSSNumericArray.values()")}} +- [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) +- [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssnumericarray/foreach/index.md b/files/en-us/web/api/cssnumericarray/foreach/index.md new file mode 100644 index 000000000000000..c6605e14b431e8b --- /dev/null +++ b/files/en-us/web/api/cssnumericarray/foreach/index.md @@ -0,0 +1,67 @@ +--- +title: "CSSNumericArray: forEach() method" +short-title: forEach() +slug: Web/API/CSSNumericArray/forEach +page-type: web-api-instance-method +browser-compat: api.CSSNumericArray.forEach +--- + +{{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} + +The **`forEach()`** method of the {{domxref("CSSNumericArray")}} interface executes a provided function once for each item in the object. + +## Syntax + +```js-nolint +forEach(callbackFn) +forEach(callbackFn, thisArg) +``` + +### Parameters + +- `callbackFn` + - : The function to execute for each element, taking three arguments: + - `currentValue` + - : The item being processed. + - `index` {{optional_inline}} + - : The index of the current element being processed. + - `array` {{optional_inline}} + - : The `CSSNumericArray` that `forEach()` is being called on. +- `thisArg` {{optional_inline}} + - : Value to use as `this` when executing `callbackFn`. + +### Return value + +None ({{jsxref("undefined")}}). + +## Examples + +### Iterating with forEach() + +```js +const sum = new CSSMathSum(CSS.px(10), CSS.em(5), CSS.percent(50)); + +sum.values.forEach((value, index) => { + console.log(index, value.toString()); +}); +// 0 "10px" +// 1 "5em" +// 2 "50%" +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("CSSNumericArray.entries()")}} +- {{domxref("CSSNumericArray.keys()")}} +- {{domxref("CSSNumericArray.length")}} +- {{domxref("CSSNumericArray.values()")}} +- [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) +- [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssnumericarray/index.md b/files/en-us/web/api/cssnumericarray/index.md index 913482f3c1dab88..3a9c9b01664503b 100644 --- a/files/en-us/web/api/cssnumericarray/index.md +++ b/files/en-us/web/api/cssnumericarray/index.md @@ -7,16 +7,49 @@ browser-compat: api.CSSNumericArray {{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} -The **`CSSNumericArray`** interface of the [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Object_Model) contains a list of {{domxref("CSSNumericValue")}} objects. +The **`CSSNumericArray`** interface of the [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Object_Model) represents an iterable of {{domxref("CSSNumericValue")}}-based objects. + +An object of this type is used to represent the operands of a mathematical operation in the `values` property of {{domxref("CSSMathSum")}}, {{domxref("CSSMathProduct")}}, {{domxref("CSSMathMin")}}, and {{domxref("CSSMathMax")}}. + +The items can be accessed by index (`array[0]`), and as an iterable it can be used with a {{jsxref("Statements/for...of", "for...of")}} loop or the spread syntax. ## Instance properties - {{domxref("CSSNumericArray.length")}} {{ReadOnlyInline}} - - : Returns how many {{domxref("CSSNumericValue")}} objects are contained within the `CSSNumericArray`. + - : Returns the number of items in the object. + +## Instance methods + +- {{domxref("CSSNumericArray.entries()")}} + - : Returns a new _array iterator_ that yields `[index, value]` pairs for each item in the object. +- {{domxref("CSSNumericArray.forEach()")}} + - : Executes a provided function once for each item in the object. +- {{domxref("CSSNumericArray.keys()")}} + - : Returns a new _array iterator_ that yields the index of each item in the object. +- {{domxref("CSSNumericArray.values()")}} + - : Returns a new _array iterator_ that yields each item in the object. ## Examples -To do. +### Reading the terms of a `CSSMathSum` + +The `values` property of a {{domxref("CSSMathSum")}} is a `CSSNumericArray` containing the terms of the sum. +This example creates a `CSSMathSum`, then reads its `values` via `length`, indexed access, and iteration. + +```js +const sum = new CSSMathSum(CSS.px(10), CSS.em(5), CSS.percent(50)); +const values = sum.values; + +console.log(values.length); // 3 +console.log(values[0]); // CSSUnitValue {value: 10, unit: "px"} + +for (const value of values) { + console.log(value.toString()); +} +// "10px" +// "5em" +// "50%" +``` ## Specifications @@ -25,3 +58,13 @@ To do. ## Browser compatibility {{Compat}} + +## See also + +- {{domxref("CSSMathSum")}} +- {{domxref("CSSMathProduct")}} +- {{domxref("CSSMathMin")}} +- {{domxref("CSSMathMax")}} +- {{domxref("CSSNumericValue")}} +- [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) +- [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssnumericarray/keys/index.md b/files/en-us/web/api/cssnumericarray/keys/index.md new file mode 100644 index 000000000000000..59d8fd5d0b66000 --- /dev/null +++ b/files/en-us/web/api/cssnumericarray/keys/index.md @@ -0,0 +1,57 @@ +--- +title: "CSSNumericArray: keys() method" +short-title: keys() +slug: Web/API/CSSNumericArray/keys +page-type: web-api-instance-method +browser-compat: api.CSSNumericArray.keys +--- + +{{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} + +The **`keys()`** method of the {{domxref("CSSNumericArray")}} interface returns a new _array iterator_ that yields the index of each item in the object. + +## Syntax + +```js-nolint +keys() +``` + +### Parameters + +None. + +### Return value + +A new [iterable iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + +## Examples + +### Iterating over indexes + +```js +const sum = new CSSMathSum(CSS.px(10), CSS.em(5), CSS.percent(50)); + +for (const index of sum.values.keys()) { + console.log(index); +} +// 0 +// 1 +// 2 +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("CSSNumericArray.entries()")}} +- {{domxref("CSSNumericArray.forEach()")}} +- {{domxref("CSSNumericArray.length")}} +- {{domxref("CSSNumericArray.values()")}} +- [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) +- [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssnumericarray/length/index.md b/files/en-us/web/api/cssnumericarray/length/index.md index d2b5b899ea13c45..cf585f987bf85c6 100644 --- a/files/en-us/web/api/cssnumericarray/length/index.md +++ b/files/en-us/web/api/cssnumericarray/length/index.md @@ -8,15 +8,23 @@ browser-compat: api.CSSNumericArray.length {{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} -The **`length`** read-only property of the {{domxref("CSSNumericArray")}} interface returns the number of {{domxref("CSSNumericValue")}} objects in the list. +The **`length`** read-only property of the {{domxref("CSSNumericArray")}} interface returns the number of items in the object. ## Value -An integer representing the number of {{domxref("CSSNumericValue")}} objects in the list. +An integer. ## Examples -To Do +### Basic usage + +In this example, we read the `length` of the {{domxref("CSSNumericArray")}} returned by the `values` property of a {{domxref("CSSMathSum")}}: + +```js +const sum = new CSSMathSum(CSS.px(10), CSS.em(5), CSS.percent(50)); + +console.log(sum.values.length); // 3 +``` ## Specifications @@ -25,3 +33,12 @@ To Do ## Browser compatibility {{Compat}} + +## See also + +- {{domxref("CSSNumericArray.entries()")}} +- {{domxref("CSSNumericArray.forEach()")}} +- {{domxref("CSSNumericArray.keys()")}} +- {{domxref("CSSNumericArray.values()")}} +- [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) +- [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssnumericarray/values/index.md b/files/en-us/web/api/cssnumericarray/values/index.md new file mode 100644 index 000000000000000..09d2037072697d4 --- /dev/null +++ b/files/en-us/web/api/cssnumericarray/values/index.md @@ -0,0 +1,57 @@ +--- +title: "CSSNumericArray: values() method" +short-title: values() +slug: Web/API/CSSNumericArray/values +page-type: web-api-instance-method +browser-compat: api.CSSNumericArray.values +--- + +{{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} + +The **`values()`** method of the {{domxref("CSSNumericArray")}} interface returns a new _array iterator_ that yields each item in the object. + +## Syntax + +```js-nolint +values() +``` + +### Parameters + +None. + +### Return value + +A new [iterable iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + +## Examples + +### Iterating over values + +```js +const sum = new CSSMathSum(CSS.px(10), CSS.em(5), CSS.percent(50)); + +for (const value of sum.values.values()) { + console.log(value.toString()); +} +// "10px" +// "5em" +// "50%" +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("CSSNumericArray.entries()")}} +- {{domxref("CSSNumericArray.forEach()")}} +- {{domxref("CSSNumericArray.keys()")}} +- {{domxref("CSSNumericArray.length")}} +- [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) +- [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssunparsedvalue/cssunparsedvalue/index.md b/files/en-us/web/api/cssunparsedvalue/cssunparsedvalue/index.md index 1f96244be515670..cf02ceead631fdb 100644 --- a/files/en-us/web/api/cssunparsedvalue/cssunparsedvalue/index.md +++ b/files/en-us/web/api/cssunparsedvalue/cssunparsedvalue/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSSUnparsedValue.CSSUnparsedValue {{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} -The **`CSSUnparsedValue()`** constructor creates a new {{domxref("CSSUnparsedValue")}} object which represents property values that reference custom properties. +The **`CSSUnparsedValue()`** constructor creates a new {{domxref("CSSUnparsedValue")}} object, which represents a property value that can't be parsed into a more specific type — typically the value of a custom property. ## Syntax @@ -19,7 +19,7 @@ new CSSUnparsedValue(members) ### Parameters - `members` - - : An array whose values must be either a string or a {{domxref('CSSVariableReferenceValue')}}. + - : An array whose values must be either a string or a {{domxref("CSSVariableReferenceValue")}}. ## Examples @@ -33,6 +33,23 @@ console.log(value); // CSSUnparsedValue {0: "4deg", length: 1} console.log(values); // CSSUnparsedValue {0: "1em", 1: "#445566", 2: "-45px", length: 3} ``` +### `CSSUnparsedValue` with a variable reference + +A member can also be a {{domxref("CSSVariableReferenceValue")}}, representing a {{cssxref("var", "var()")}} reference embedded in the value. +This example builds a `CSSUnparsedValue` for a declaration equivalent to `10px var(--bar, blue)`. + +```js +const fallback = new CSSUnparsedValue(["blue"]); +const varRef = new CSSVariableReferenceValue("--bar", fallback); + +const value = new CSSUnparsedValue(["10px ", varRef]); + +console.log(value.length); // 2 +console.log(value[0]); // "10px " +console.log(value[1].variable); // "--bar" +console.log(value[1].fallback[0]); // "blue" +``` + ## Specifications {{Specifications}} @@ -43,10 +60,11 @@ console.log(values); // CSSUnparsedValue {0: "1em", 1: "#445566", 2: "-45px", le ## See also -- {{domxref("CSSUnparsedValue.entries")}} -- {{domxref("CSSUnparsedValue.forEach")}} -- {{domxref("CSSUnparsedValue.keys")}} +- {{domxref("CSSVariableReferenceValue")}} +- {{domxref("CSSUnparsedValue.entries()")}} +- {{domxref("CSSUnparsedValue.forEach()")}} +- {{domxref("CSSUnparsedValue.keys()")}} - {{domxref("CSSUnparsedValue.length")}} -- {{domxref("CSSUnparsedValue.values")}} +- {{domxref("CSSUnparsedValue.values()")}} - [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) - [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssunparsedvalue/entries/index.md b/files/en-us/web/api/cssunparsedvalue/entries/index.md index 946d6c1eab1f294..25c68d14819938a 100644 --- a/files/en-us/web/api/cssunparsedvalue/entries/index.md +++ b/files/en-us/web/api/cssunparsedvalue/entries/index.md @@ -8,22 +8,36 @@ browser-compat: api.CSSUnparsedValue.entries {{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} -The **`CSSUnparsedValue.entries()`** method returns an array of a given object's own enumerable property `[key, value]` pairs in the same order as that provided by a {{jsxref("Statements/for...in", "for...in")}} loop (the difference being that a for-in loop enumerates properties in the prototype chain as well). +The **`entries()`** method of the {{domxref("CSSUnparsedValue")}} interface returns a new _array iterator_ that yields `[index, value]` pairs for each item in the object. ## Syntax ```js-nolint -entries(obj) +entries() ``` ### Parameters -- `obj` - - : The {{domxref('CSSUnparsedValue')}} whose enumerable own property `[key, value]` pairs are to be returned. +None. ### Return value -An array of the given `CSSUnparsedValue` object's own enumerable property `[key, value]` pairs. +A new [iterable iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + +## Examples + +### Iterating over index/value pairs + +```js +const value = new CSSUnparsedValue(["1em", "#445566", "-45px"]); + +for (const [index, fragment] of value.entries()) { + console.log(index, fragment); +} +// 0 "1em" +// 1 "#445566" +// 2 "-45px" +``` ## Specifications @@ -36,9 +50,9 @@ An array of the given `CSSUnparsedValue` object's own enumerable property `[key, ## See also - {{domxref("CSSUnparsedValue.CSSUnparsedValue", "CSSUnparsedValue()")}} -- {{domxref("CSSUnparsedValue.forEach")}} -- {{domxref("CSSUnparsedValue.keys")}} +- {{domxref("CSSUnparsedValue.forEach()")}} +- {{domxref("CSSUnparsedValue.keys()")}} - {{domxref("CSSUnparsedValue.length")}} -- {{domxref("CSSUnparsedValue.values")}} +- {{domxref("CSSUnparsedValue.values()")}} - [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) - [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssunparsedvalue/foreach/index.md b/files/en-us/web/api/cssunparsedvalue/foreach/index.md index 6ff1fd61208e749..1feba678b65cf33 100644 --- a/files/en-us/web/api/cssunparsedvalue/foreach/index.md +++ b/files/en-us/web/api/cssunparsedvalue/foreach/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSSUnparsedValue.forEach {{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} -The **`CSSUnparsedValue.forEach()`** method executes a provided function once for each element of the {{domxref('CSSUnparsedValue')}}. +The **`forEach()`** method of the {{domxref("CSSUnparsedValue")}} interface executes a provided function once for each item in the object. ## Syntax @@ -22,20 +22,33 @@ forEach(callbackFn, thisArg) - `callbackFn` - : The function to execute for each element, taking three arguments: - `currentValue` - - : The value of the current element being processed. + - : The item being processed. - `index` {{optional_inline}} - : The index of the current element being processed. - `array` {{optional_inline}} - : The `CSSUnparsedValue` that `forEach()` is being called on. - -- `thisArg` {{Optional_inline}} - - : Value to use as **`this`** (i.e., the reference - `Object`) when executing `callback`. +- `thisArg` {{optional_inline}} + - : Value to use as `this` when executing `callbackFn`. ### Return value None ({{jsxref("undefined")}}). +## Examples + +### Iterating with forEach() + +```js +const value = new CSSUnparsedValue(["1em", "#445566", "-45px"]); + +value.forEach((fragment, index) => { + console.log(index, fragment); +}); +// 0 "1em" +// 1 "#445566" +// 2 "-45px" +``` + ## Specifications {{Specifications}} @@ -47,9 +60,9 @@ None ({{jsxref("undefined")}}). ## See also - {{domxref("CSSUnparsedValue.CSSUnparsedValue", "CSSUnparsedValue()")}} -- {{domxref("CSSUnparsedValue.entries")}} -- {{domxref("CSSUnparsedValue.keys")}} +- {{domxref("CSSUnparsedValue.entries()")}} +- {{domxref("CSSUnparsedValue.keys()")}} - {{domxref("CSSUnparsedValue.length")}} -- {{domxref("CSSUnparsedValue.values")}} +- {{domxref("CSSUnparsedValue.values()")}} - [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) - [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssunparsedvalue/index.md b/files/en-us/web/api/cssunparsedvalue/index.md index 8288c102d7079b2..c9b8fa963fd556b 100644 --- a/files/en-us/web/api/cssunparsedvalue/index.md +++ b/files/en-us/web/api/cssunparsedvalue/index.md @@ -7,10 +7,11 @@ browser-compat: api.CSSUnparsedValue {{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} -The **`CSSUnparsedValue`** interface of the [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Object_Model) represents property values that reference [custom properties](/en-US/docs/Web/CSS/Guides/Cascading_variables). -It consists of a list of string fragments and variable references. +The **`CSSUnparsedValue`** interface of the [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Object_Model) represents a property value that can't be parsed into a more specific type — typically the value of a [custom property](/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties). -Custom properties are represented by `CSSUnparsedValue` and {{cssxref("var", "var()")}} references are represented using {{domxref('CSSVariableReferenceValue')}}. +The object is an iterable that may contain string fragments and variable references. + +The items can be accessed and set by index (`unparsedValue[0]`), and as an iterable it can be used with a {{jsxref("Statements/for...of", "for...of")}} loop or the spread syntax. {{InheritanceDiagram}} @@ -21,21 +22,99 @@ Custom properties are represented by `CSSUnparsedValue` and {{cssxref("var", "va ## Instance properties -- {{domxref('CSSUnparsedValue.length')}} {{ReadOnlyInline}} - - : Returns the number of items in the `CSSUnparsedValue` object. +- {{domxref("CSSUnparsedValue.length")}} {{ReadOnlyInline}} + - : Returns the number of items in the object. ## Instance methods -_Also inherits methods from its parent interface, {{DOMxRef("CSSStyleValue")}}._ +_Also inherits methods from its parent interface, {{domxref("CSSStyleValue")}}._ + +- {{domxref("CSSUnparsedValue.entries()")}} + - : Returns a new _array iterator_ that yields `[index, value]` pairs for each item in the object. +- {{domxref("CSSUnparsedValue.forEach()")}} + - : Executes a provided function once for each item in the object. +- {{domxref("CSSUnparsedValue.keys()")}} + - : Returns a new _array iterator_ that yields the index of each item in the object. +- {{domxref("CSSUnparsedValue.values()")}} + - : Returns a new _array iterator_ that yields each item in the object. + +## Description + +A `CSSUnparsedValue` instance is an iterable of items, where each item is either a string representing a fragment of CSS text that wasn't further parsed, or a {{domxref("CSSVariableReferenceValue")}} object representing a {{cssxref("var", "var()")}} function in the value (if any were specified). + +For example, given the custom property: + +```css +--foo: 10px var(--bar, blue); +``` + +The `CSSUnparsedValue` for `--foo` has two items: + +- `"10px "`: a plain string fragment. +- A `CSSVariableReferenceValue`: representing `var(--bar, blue)`, with its own {{domxref("CSSVariableReferenceValue.variable", "variable")}} (`"--bar"`) and {{domxref("CSSVariableReferenceValue.fallback", "fallback")}} (a nested `CSSUnparsedValue` for `blue`). + +### Parsing a `CSSUnparsedValue` further + +`CSSUnparsedValue` preserves the raw, unparsed text of a value: it doesn't interpret that text as a length, a color, or any other more specific type. + +If you know what kind of value the text represents, you can parse it further using the static `parse()` method of the type you expect, such as {{domxref("CSSNumericValue/parse_static", "CSSNumericValue.parse()")}} for a numeric value with a unit, or the more general {{domxref("CSSStyleValue/parse_static", "CSSStyleValue.parse()")}}, which additionally requires you to specify the target CSS property name. + +These `parse()` methods take a CSS text string, not a `CSSUnparsedValue` object. +However since `CSSUnparsedValue` inherits the {{domxref("CSSStyleValue.toString()")}} stringifier, it can be passed directly wherever a string is expected. +Parsing throws a `SyntaxError` if the text doesn't match the syntax expected by the type you're parsing it as. + +## Examples + +### Creating, reading, and updating a `CSSUnparsedValue` + +This example creates a `CSSUnparsedValue`, then reads its items via `length`, indexed access, and iteration, and finally updates one of the items by assigning to its index. + +```js +const value = new CSSUnparsedValue(["1em", "#445566", "-45px"]); + +console.log(value.length); // 3 +console.log(value[0]); // "1em" + +for (const fragment of value) { + console.log(fragment); +} +// "1em" +// "#445566" +// "-45px" + +value[0] = "2em"; +console.log(value[0]); // "2em" +``` + +### Reading and parsing a custom property's value + +A `CSSUnparsedValue` is what you get back when you read the value of a custom property from a {{domxref("StylePropertyMapReadOnly")}}, since the browser cannot know in advance what kind of value the property holds. +This example reads the `--unit` custom property from an element's computed style map, then parses it into a {{domxref("CSSUnitValue")}} using {{domxref("CSSNumericValue/parse_static", "CSSNumericValue.parse()")}}. + +```html + +``` + +```css +#btn { + --unit: 1.2rem; + padding: var(--unit); +} +``` + +```js +const styleMap = document.getElementById("btn").computedStyleMap(); +const unit = styleMap.get("--unit"); + +console.log(unit); // CSSUnparsedValue {0: " 1.2rem", length: 1} +console.log(unit[0]); // " 1.2rem" + +const parsedUnit = CSSNumericValue.parse(unit); +console.log(parsedUnit.value); // 1.2 +console.log(parsedUnit.unit); // "rem" +``` -- {{domxref('CSSUnparsedValue.entries()')}} - - : Returns an array of a given object's own enumerable property `[key, value]` pairs in the same order as that provided by a {{jsxref("Statements/for...in", "for...in")}} loop (the difference being that a for-in loop enumerates properties in the prototype chain as well). -- {{domxref('CSSUnparsedValue.forEach()')}} - - : Executes a provided function once for each element of the `CSSUnparsedValue` object. -- {{domxref('CSSUnparsedValue.keys()')}} - - : Returns a new _array iterator_ object that contains the keys for each index in the `CSSUnparsedValue` object. -- {{domxref('CSSUnparsedValue.values()')}} - - : Returns a new _array iterator_ object that contains the values for each index in the `CSSUnparsedValue` object. +See the [`CSSUnparsedValue` section](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide#cssunparsedvalue) of the _CSS Typed OM guide_ for more detail on this example. ## Specifications @@ -47,10 +126,11 @@ _Also inherits methods from its parent interface, {{DOMxRef("CSSStyleValue")}}._ ## See also -- {{domxref('CSSImageValue')}} -- {{domxref('CSSKeywordValue')}} -- {{domxref('CSSNumericValue')}} -- {{domxref('CSSPositionValue')}} -- {{domxref('CSSTransformValue')}} +- {{domxref("CSSVariableReferenceValue")}} +- {{domxref("CSSImageValue")}} +- {{domxref("CSSKeywordValue")}} +- {{domxref("CSSNumericValue")}} +- {{domxref("CSSPositionValue")}} +- {{domxref("CSSTransformValue")}} - [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) - [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssunparsedvalue/keys/index.md b/files/en-us/web/api/cssunparsedvalue/keys/index.md index d9072457383d2b4..aadf8d3bbc7489b 100644 --- a/files/en-us/web/api/cssunparsedvalue/keys/index.md +++ b/files/en-us/web/api/cssunparsedvalue/keys/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSSUnparsedValue.keys {{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} -The **`CSSUnparsedValue.keys()`** method returns a new _array iterator_ object that contains the keys for each index in the array. +The **`keys()`** method of the {{domxref("CSSUnparsedValue")}} interface returns a new _array iterator_ that yields the index of each item in the object. ## Syntax @@ -22,7 +22,22 @@ None. ### Return value -A new {{jsxref("Array")}}. +A new [iterable iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + +## Examples + +### Iterating over indexes + +```js +const value = new CSSUnparsedValue(["1em", "#445566", "-45px"]); + +for (const index of value.keys()) { + console.log(index); +} +// 0 +// 1 +// 2 +``` ## Specifications @@ -35,9 +50,9 @@ A new {{jsxref("Array")}}. ## See also - {{domxref("CSSUnparsedValue.CSSUnparsedValue", "CSSUnparsedValue()")}} -- {{domxref("CSSUnparsedValue.entries")}} -- {{domxref("CSSUnparsedValue.forEach")}} +- {{domxref("CSSUnparsedValue.entries()")}} +- {{domxref("CSSUnparsedValue.forEach()")}} - {{domxref("CSSUnparsedValue.length")}} -- {{domxref("CSSUnparsedValue.values")}} +- {{domxref("CSSUnparsedValue.values()")}} - [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) - [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssunparsedvalue/length/index.md b/files/en-us/web/api/cssunparsedvalue/length/index.md index d62a06480a1a21c..a9e4d668d30a0be 100644 --- a/files/en-us/web/api/cssunparsedvalue/length/index.md +++ b/files/en-us/web/api/cssunparsedvalue/length/index.md @@ -21,9 +21,9 @@ An integer. In this example, we use the {{domxref("CSSUnparsedValue.CSSUnparsedValue", "CSSUnparsedValue()")}} constructor, then query the length: ```js -const values = new CSSUnparsedValue(["1em", "#445566", "-45px"]); +const value = new CSSUnparsedValue(["1em", "#445566", "-45px"]); -console.log(values.length); // 3 +console.log(value.length); // 3 ``` ## Specifications @@ -37,9 +37,9 @@ console.log(values.length); // 3 ## See also - {{domxref("CSSUnparsedValue.CSSUnparsedValue", "CSSUnparsedValue()")}} -- {{domxref("CSSUnparsedValue.entries")}} -- {{domxref("CSSUnparsedValue.forEach")}} -- {{domxref("CSSUnparsedValue.keys")}} -- {{domxref("CSSUnparsedValue.values")}} +- {{domxref("CSSUnparsedValue.entries()")}} +- {{domxref("CSSUnparsedValue.forEach()")}} +- {{domxref("CSSUnparsedValue.keys()")}} +- {{domxref("CSSUnparsedValue.values()")}} - [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) - [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) diff --git a/files/en-us/web/api/cssunparsedvalue/values/index.md b/files/en-us/web/api/cssunparsedvalue/values/index.md index 3097ebe5a9d1684..a8a8bf61f35741c 100644 --- a/files/en-us/web/api/cssunparsedvalue/values/index.md +++ b/files/en-us/web/api/cssunparsedvalue/values/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSSUnparsedValue.values {{APIRef("CSS Typed Object Model API")}} {{AvailableInWorkers}} -The **`CSSUnparsedValue.values()`** method returns a new _array iterator_ object that contains the values for each index in the CSSUnparsedValue object. +The **`values()`** method of the {{domxref("CSSUnparsedValue")}} interface returns a new _array iterator_ that yields each item in the object. ## Syntax @@ -22,7 +22,22 @@ None. ### Return value -A new {{jsxref("Array")}}. +A new [iterable iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + +## Examples + +### Iterating over values + +```js +const value = new CSSUnparsedValue(["1em", "#445566", "-45px"]); + +for (const fragment of value.values()) { + console.log(fragment); +} +// "1em" +// "#445566" +// "-45px" +``` ## Specifications @@ -35,9 +50,9 @@ A new {{jsxref("Array")}}. ## See also - {{domxref("CSSUnparsedValue.CSSUnparsedValue", "CSSUnparsedValue()")}} -- {{domxref("CSSUnparsedValue.entries")}} -- {{domxref("CSSUnparsedValue.forEach")}} -- {{domxref("CSSUnparsedValue.keys")}} +- {{domxref("CSSUnparsedValue.entries()")}} +- {{domxref("CSSUnparsedValue.forEach()")}} +- {{domxref("CSSUnparsedValue.keys()")}} - {{domxref("CSSUnparsedValue.length")}} - [Using the CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) - [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) From 620c181285150bdb00b1abc2974251d18560efd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ky=E2=84=93e=20Hensel?= Date: Sat, 15 Aug 2026 12:44:14 +1200 Subject: [PATCH 2/2] on macOS, middle-click is not used for pasting (#45035) on macos, middle-click is not used for pasting --- files/en-us/web/api/element/auxclick_event/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/element/auxclick_event/index.md b/files/en-us/web/api/element/auxclick_event/index.md index d7a9b3231520194..9d46e924a21338d 100644 --- a/files/en-us/web/api/element/auxclick_event/index.md +++ b/files/en-us/web/api/element/auxclick_event/index.md @@ -35,7 +35,7 @@ A {{domxref("PointerEvent")}}. Inherits from {{domxref("MouseEvent")}}. For the vast majority of browsers that map middle click to opening a link in a new tab, including Firefox, it is possible to cancel this behavior by calling {{domxref("Event.preventDefault()", "preventDefault()")}} from within an `auxclick` event handler. -When listening for `auxclick` events originating on elements that do not support input or navigation, you will often want to explicitly prevent other default actions mapped to the down action of the middle mouse button. On Windows this is usually autoscroll, and on macOS and Linux this is usually clipboard paste. This can be done by preventing the default behavior of the {{domxref("Element/mousedown_event", "mousedown")}} or {{domxref("Element/pointerdown_event", "pointerdown")}} event. +When listening for `auxclick` events originating on elements that do not support input or navigation, you will often want to explicitly prevent other default actions mapped to the down action of the middle mouse button. On Windows this is usually autoscroll, and on Linux this is usually clipboard paste. This can be done by preventing the default behavior of the {{domxref("Element/mousedown_event", "mousedown")}} or {{domxref("Element/pointerdown_event", "pointerdown")}} event. Additionally, you may need to avoid opening a system context menu after a right click. Due to timing differences between operating systems, this too is not a preventable default behavior of `auxclick`. Instead, this can be done by preventing the default behavior of the {{domxref("Element/contextmenu_event", "contextmenu")}} event.