Skip to content

Commit 59e9fd4

Browse files
rachelandrewjpmedley
rachelandrew
and
jpmedley
authored
Adds CustomStateSet (mdn#8093)
* Adds CustomStateSet * Adding set methods (mdn#2) * Adding set methods * case * and back * Apply suggestions from code review Co-authored-by: Joe Medley <jmedley@google.com> Co-authored-by: Joe Medley <jmedley@google.com>
1 parent 1467809 commit 59e9fd4

File tree

12 files changed

+449
-20
lines changed

12 files changed

+449
-20
lines changed

‎files/en-us/web/api/customstateset/add/index.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: CustomStateSet.add()
3+
slug: Web/API/CustomStateSet/add
4+
tags:
5+
- API
6+
- Method
7+
- Reference
8+
- add
9+
- CustomStateSet
10+
browser-compat: api.CustomStateSet.add
11+
---
12+
{{DefaultAPISidebar("DOM")}}
13+
14+
The **`add`** method of the {{domxref("CustomStateSet")}} interface adds an item to the `CustomStateSet`, after checking that the value is in the correct format.
15+
16+
## Syntax
17+
18+
```js
19+
CustomStateSet.add(value)
20+
```
21+
22+
### Parameters
23+
24+
- `value`
25+
- : A {{domxref("DOMString")}} which must be a `<dashed-ident>`, with the form `--mystate`.
26+
27+
### Return Value
28+
29+
Undefined.
30+
31+
### Exceptions
32+
33+
- {{domxref("DOMException")}} `SyntaxError`
34+
- : Thrown if the string is not a `<dashed-ident>`.
35+
36+
## Examples
37+
38+
The following function adds the state `--checked` to a `CustomStateSet`.
39+
40+
```js
41+
set checked(flag) {
42+
if (flag) {
43+
this._internals.states.add('--checked');
44+
}
45+
```
46+
47+
## Specifications
48+
49+
{{Specifications}}
50+
51+
## Browser compatibility
52+
53+
{{Compat}}
54+

‎files/en-us/web/api/customstateset/clear/index.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: CustomStateSet.clear()
3+
slug: Web/API/CustomStateSet/clear
4+
tags:
5+
- API
6+
- Method
7+
- Reference
8+
- clear
9+
- CustomStateSet
10+
browser-compat: api.CustomStateSet.clear
11+
---
12+
{{DefaultAPISidebar("DOM")}}
13+
14+
The **`clear()`** method of the {{domxref("CustomStateSet")}} interface removes all elements from the `CustomStateSet` object.
15+
16+
## Syntax
17+
18+
```js
19+
CustomStateSet.clear()
20+
```
21+
22+
### Parameters
23+
24+
None.
25+
26+
### Return Value
27+
28+
Undefined.
29+
30+
## Specifications
31+
32+
{{Specifications}}
33+
34+
## Browser compatibility
35+
36+
{{Compat}}
37+

‎files/en-us/web/api/customstateset/delete/index.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: CustomStateSet.delete()
3+
slug: Web/API/CustomStateSet/delete
4+
tags:
5+
- API
6+
- Method
7+
- Reference
8+
- delete
9+
- CustomStateSet
10+
browser-compat: api.CustomStateSet.delete
11+
---
12+
{{DefaultAPISidebar("DOM")}}
13+
14+
The **`delete()`** method of the {{domxref("CustomStateSet")}} interface deletes a single value from the `CustomStateSet`.
15+
16+
## Syntax
17+
18+
```js
19+
CustomStateSet.delete(value)
20+
```
21+
22+
### Parameters
23+
24+
: `value`
25+
: - The value to remove from the `CustomStateSet`.
26+
27+
### Return Value
28+
29+
Returns `true` if `value` was in the `CustomStateSet`; otherwise `false`.
30+
31+
## Specifications
32+
33+
{{Specifications}}
34+
35+
## Browser compatibility
36+
37+
{{Compat}}
38+

‎files/en-us/web/api/customstateset/entries/index.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: CustomStateSet.entries()
3+
slug: Web/API/CustomStateSet/entries
4+
tags:
5+
- API
6+
- Method
7+
- Reference
8+
- entries
9+
- CustomStateSet
10+
browser-compat: api.CustomStateSet.entries
11+
---
12+
{{DefaultAPISidebar("DOM")}}
13+
14+
The **`entries`** method of the {{domxref("CustomStateSet")}} interface returns a new {{jsxref("Iterator")}} object, containing an array of `[value,value]` for each element in the `CustomStateSet`.
15+
16+
## Syntax
17+
18+
```js
19+
CustomStateSet.entries()
20+
```
21+
22+
### Parameters
23+
24+
None.
25+
26+
### Return Value
27+
28+
A new iterator object that contains an array of `[value, value]` for each element in the `CustomStateSet`, in insertion order.
29+
30+
## Specifications
31+
32+
{{Specifications}}
33+
34+
## Browser compatibility
35+
36+
{{Compat}}
37+

‎files/en-us/web/api/customstateset/foreach/index.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: CustomStateSet.forEach()
3+
slug: Web/API/CustomStateSet/forEach
4+
tags:
5+
- API
6+
- Method
7+
- Reference
8+
- forEach
9+
- CustomStateSet
10+
browser-compat: api.CustomStateSet.forEach
11+
---
12+
{{DefaultAPISidebar("DOM")}}
13+
14+
The **`forEach()`** method of the {{domxref("CustomStateSet")}} interface executes a provided function for each value in the `CustomStateSet` object.
15+
16+
## Syntax
17+
18+
```js
19+
CustomStateSet.forEach(callbackFn)
20+
CustomStateSet.forEach(callbackFn, thisArg)
21+
```
22+
23+
### Parameters
24+
25+
- `callbackFn`
26+
- : Function to execute for each element, taking three arguments:
27+
- `value`, `key`
28+
- : The current element being processed in the `CustomStateSet`. As there are no keys in a `CustomStateSet`, the value is passed for both arguments.
29+
- `set`
30+
- : The `CustomStateSet` which `forEach()` was called upon.
31+
- `thisArg`
32+
- : Value to use as `this` when executing `callbackFn`.
33+
34+
### Return Value
35+
36+
Undefined.
37+
38+
## Specifications
39+
40+
{{Specifications}}
41+
42+
## Browser compatibility
43+
44+
{{Compat}}
45+

‎files/en-us/web/api/customstateset/has/index.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: CustomStateSet.has()
3+
slug: Web/API/CustomStateSet/has
4+
tags:
5+
- API
6+
- Method
7+
- Reference
8+
- has
9+
- CustomStateSet
10+
browser-compat: api.CustomStateSet.has
11+
---
12+
{{DefaultAPISidebar("DOM")}}
13+
14+
The **`has()`** method of the {{domxref("CustomStateSet")}} interface returns a {{jsxref("Boolean")}} asserting whether an element is present with the given value.
15+
16+
## Syntax
17+
18+
```js
19+
CustomStateSet.has(value)
20+
```
21+
22+
### Parameters
23+
24+
- `value`
25+
- : The value to test for in the `CustomStateSet` object.
26+
27+
### Return Value
28+
29+
A {{jsxref("Boolean")}}, `true` if `value` exists in the `CustomStateSet`.
30+
31+
## Specifications
32+
33+
{{Specifications}}
34+
35+
## Browser compatibility
36+
37+
{{Compat}}
38+

‎files/en-us/web/api/customstateset/index.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: CustomStateSet
3+
slug: Web/API/CustomStateSet
4+
tags:
5+
- API
6+
- Interface
7+
- Reference
8+
- CustomStateSet
9+
browser-compat: api.CustomStateSet
10+
---
11+
{{DefaultAPISidebar("DOM")}}
12+
13+
The **`CustomStateSet`** interface of the {{domxref('Document_Object_Model','','',' ')}} stores a list of possible states for a custom element to be in, and allows states to be added and removed from the set.
14+
15+
## Description
16+
17+
An HTML form element, such as a checkbox has different _states_, "checked" and "unchecked". Likewise, developers creating custom elements need to assign possible states to these elements. The `CustomStateList` allows these states to be stored, and accessed from the custom element.
18+
19+
A instance of `CustomStateList` is returned by {{domxref("ElementInternals.states")}}. The `CustomStateList` object is described as _setlike_, and therefore the methods behave in a similar manner to those on a {{jsxref("Set")}}.
20+
21+
Each value stored in a `CustomStateList` is a `<dashed-ident>`, in the format `--mystate`.
22+
23+
### Interaction with CSS
24+
25+
States are stored as a `<dashed-ident>` as this format can then be accessed from CSS using the _custom state pseudo-class_.
26+
In the same way that you can use CSS to determine if a checkbox is checked using the {{cssxref(":checked")}} pseudo-class,
27+
you can use a custom state pseudo-class to select a custom element that is in a certain state.
28+
29+
## Properties
30+
31+
- {{domxref("CustomStateSet.size")}}
32+
- : Returns the number of values in the `CustomStateSet`.
33+
34+
## Methods
35+
36+
- {{domxref("CustomStateSet.add()")}}
37+
- : Adds a value to the set, first checking that the _value_ is a `<dashed-ident>`.
38+
- {{domxref("CustomStateSet.clear()")}}
39+
- : Removes all elements from the `CustomStateSet` object.
40+
- {{domxref("CustomStateSet.delete()")}}
41+
- : Removes one value from the `CustomStateSet` object.
42+
- {{domxref("CustomStateSet.entries()")}}
43+
- : Returns a new iterator with the values for each element in the `CustomStateSet` in insertion order.
44+
- {{domxref("CustomStateSet.forEach()")}}
45+
- : Executes a provided function for each value in the `CustomStateSet` object.
46+
- {{domxref("CustomStateSet.has()")}}
47+
- : Returns a {{jsxref("Boolean")}} asserting whether an element is present with the given value.
48+
- {{domxref("CustomStateSet.keys()")}}
49+
- : An alias for {{domxref("CustomStateSet.values()")}}.
50+
- {{domxref("CustomStateSet.values()")}}
51+
- : Returns a new iterator object that yields the values for each element in the `CustomStateSet` object in insertion order.
52+
53+
## Examples
54+
55+
The following function adds and removes the state `--checked` to a `CustomStateSet`, then prints to the console `true` or `false` as the custom checkbox is checked or unchecked.
56+
57+
The state of the element can be accessed from CSS using the custom state pseudo-class `--checked`.
58+
59+
```js
60+
set checked(flag) {
61+
if (flag) {
62+
this._internals.states.add('--checked');
63+
} else {
64+
this._internals.states.delete('--checked');
65+
}
66+
67+
console.log(this._internals.states.has('--checked'));
68+
}
69+
```
70+
71+
```css
72+
labeled-checkbox { border: dashed red; }
73+
labeled-checkbox:--checked { border: solid; }
74+
```
75+
76+
## Specifications
77+
78+
{{Specifications}}
79+
80+
## Browser compatibility
81+
82+
{{Compat}}
83+

‎files/en-us/web/api/customstateset/keys/index.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: CustomStateSet.keys()
3+
slug: Web/API/CustomStateSet/keys
4+
tags:
5+
- API
6+
- Method
7+
- Reference
8+
- keys
9+
- CustomStateSet
10+
browser-compat: api.CustomStateSet.keys
11+
---
12+
{{DefaultAPISidebar("DOM")}}
13+
14+
The **`keys()`** method of the {{domxref("CustomStateSet")}} interface is an alias for {{domxref("CustomStateSet.values")}}.
15+
16+
## Syntax
17+
18+
```js
19+
CustomStateSet.keys()
20+
```
21+
22+
### Return Value
23+
24+
A new iterator object containing the values for each element in the given `CustomStateSet`, in insertion order.
25+
26+
## Specifications
27+
28+
{{Specifications}}
29+
30+
## Browser compatibility
31+
32+
{{Compat}}
33+

0 commit comments

Comments
 (0)