Skip to content

Commit

Permalink
Replace getSupported method with validValues attribute
Browse files Browse the repository at this point in the history
  • Loading branch information
lukewarlow committed Sep 18, 2023
1 parent bfec2c5 commit 91bc25d
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 36 deletions.
3 changes: 1 addition & 2 deletions README.md
Expand Up @@ -91,13 +91,12 @@ interface PreferenceManager {
readonly reducedTransparency: PreferenceObject;
readonly reducedData: PreferenceObject;
// Future preferences can be added here, the exact properties will be down to the browser support.

getSupported(): PreferenceSupportData[];
}

interface PreferenceObject {
// null means the preference is not overridden
readonly override: string | null;
readonly validValues: string[];

requestOverride(value: string): Promise<void>;
clearOverride(): void;
Expand Down
55 changes: 21 additions & 34 deletions index.bs
Expand Up @@ -184,42 +184,13 @@ If an override is set for this preference:
- The user agent MUST also use this override when calculating the [[SAVEDATA#savedata-attribute]].
- The user agent MUST also use this override for any UA features that are normally affected by [[mediaqueries-5#prefers-reduced-data]].

## {{getSupported}} method ## {#get-supported-method}

<div algorithm>
The <dfn method for=PreferenceManager>getSupported()</dfn> method, when invoked, must run these steps:

1. Let |supportedPreferences| be a new empty [=sequence=].
1. For each preference that the browser supports, let |preference| be the name of that preference:
1. Let |preferenceData| be a new {{PreferenceSupportData}} object.
1. Let |values| be a new empty [=sequence=].
1. If |preference| is "{{colorScheme}}", set |values| to the result of [=get valid values for colorScheme=].
1. If |preference| is "{{contrast}}", set |values| to the result of [=get valid values for contrast=].
1. If |preference| is "{{reducedMotion}}", set |values| to the result of [=get valid values for reducedMotion=].
1. If |preference| is "{{reducedTransparency}}", set |values| to the result of [=get valid values for reducedTransparency=].
1. If |preference| is "{{reducedData}}", set |values| to the result of [=get valid values for reducedData=].
1. Set |preferenceData|'s {{name}} attribute to |preference|.
1. Set |preferenceData|'s {{values}} attribute to |values|.
1. Add |preferenceData| to |supportedPreferences|.
1. Return |supportedPreferences|.
</div>

### {{PreferenceSupportData}} interface ### {#preferencesupportdata-interface}

<script type=idl>
[Exposed=Window, SecureContext]
interface PreferenceSupportData {
readonly attribute DOMString name;
readonly attribute FrozenArray<DOMString> values;
};
</script>

## {{PreferenceObject}} interface ## {#preferenceobject-interface}

<script type=idl>
[Exposed=Window, SecureContext]
interface PreferenceObject {
readonly attribute DOMString? override;
readonly attribute FrozenArray<DOMString> validValues;

undefined clearOverride();
Promise<undefined> requestOverride(DOMString value);
Expand All @@ -237,6 +208,21 @@ interface PreferenceObject {
1. Return |override|.
</div>

### {{validValues}} attribute ### {#validValues-attribute}

<div algorithm>
The <dfn attribute for=PreferenceObject>validValues</dfn> attribute, when accessed, must run these steps:

1. Let |preference| be the preference object's name.
1. Let |validValues| be a new empty [=sequence=].
1. If |preference| is "{{colorScheme}}", set |validValues| to the result of [=get valid values for colorScheme=].
1. If |preference| is "{{contrast}}", set |validValues| to the result of [=get valid values for contrast=].
1. If |preference| is "{{reducedMotion}}", set |validValues| to the result of [=get valid values for reducedMotion=].
1. If |preference| is "{{reducedTransparency}}", set |validValues| to the result of [=get valid values for reducedTransparency=].
1. If |preference| is "{{reducedData}}", set |validValues| to the result of [=get valid values for reducedData=].
1. Return |validValues|.
</div>

### {{requestOverride()}} method ### {#request-override-method}

<div algorithm='request preference override'>
Expand Down Expand Up @@ -325,15 +311,16 @@ Each preference property's override property will return the string value indica
const colorScheme = navigator.preferences.colorScheme.override; // "light" | "dark" | null
```

## The `navigator.preferences.getSupported` method ## {#get-supported}
## Getting valid values for a preference ## {#get-validValues}

Each {{PreferenceObject}} contains a validValues attribute that can be used to determine the valid values for a preference.

This method allows a site to get the preferences supported by the browser. This is useful for sites that want to dynamically generate UI for overriding preferences.
This is useful for sites that want to dynamically generate UI for overriding preferences.

It also allows sites to determine if a preference value is supported before attempting to set it.

```js
const preferenceSupportData = navigator.preferences.getSupported();
console.log(preferenceSupportData); // [ { name: 'contrast', values: ['more', 'less', 'no-preference'] }, ... ]
const validValues = navigator.preferences.colorScheme.validValues; // ["light", "dark"]
```

# Security and Privacy Considerations # {#sec-security}
Expand Down

0 comments on commit 91bc25d

Please sign in to comment.